Agent ID

What it is

An Agent ID is the identity and credential set that connects your AI agent to a user's FluxA Wallet. It consists of three parts:

• agent_id — unique identifier for the agent
• token — persistent secret used to refresh credentials
• jwt — short-lived bearer token for calling payment and payout APIs

Every agent must register an Agent ID before it can spend, receive, or manage funds on behalf of a user.

What agents can do with it

• Authenticate — attach the JWT as Authorization: Bearer to all FluxA API calls.
• Refresh credentials — use the token to obtain a fresh JWT when the current one expires.
• Onboard users — if the agent is not yet authorized in a user's wallet, the API returns an authorizationUrl the user can open to grant access.
• Sign in to third-party services — issue a short-lived Verifiable Credential (VC) bound to a specific verifier, so external services can accept the Agent ID as a login without ever seeing your JWT.

Related APIs

Method	Endpoint	Description
POST	/register	Register a new agent — returns agent_id, token, jwt
POST	/refresh	Refresh an expired JWT using agent_id + token
POST	/agent/vc/issue	Issue a VC for a third-party verifier (login-JWT protected)
POST	/verify-vc	Helper to verify a VC server-side (debugging / no-JWT-lib)
GET	/.well-known/jwks.json	RS256 public keys used to verify login JWTs and VCs

Using the Agent ID with third parties

If an external service ("SSO partner", "monetized API behind a non-FluxA proxy", "account-linking dashboard") supports Fluxa Agent ID login, the agent does not give it the login JWT. Instead:

1. The third party returns a challenge and its audience identifier.
2. The agent calls /agent/vc/issue with its login JWT to mint a VC bound to that challenge + audience.
3. The agent submits the VC; the third party verifies it locally against FluxA's JWKS and uses payload.sub as the agent identity.

Walk-throughs:

• Agent-side flow: Log in to a Third-Party Service with Agent ID
• Verifier-side flow (for the third party): Verify Fluxa Agent ID
• Endpoint reference: Verifiable Credential (VC) API

Integration flow

Below is an example prompt you can give an AI agent to register and set up its Agent ID.

** Your task **
Register with FluxA to obtain payment credentials, then verify
the credentials work.

** Step 1 — Register **
Call the registration endpoint to get your Agent ID credentials:

curl -X POST https://agentid.fluxapay.xyz/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "My Trading Agent",
    "client_info": "trading-bot-v1"
  }'

The response returns agent_id, token, and jwt.
Store all three values securely — you will need them for every
subsequent API call.

** Step 2 — Refresh JWT when expired **
JWTs expire periodically. When you receive a 401 from any FluxA
API, refresh your JWT:

curl -X POST https://agentid.fluxapay.xyz/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<YOUR_AGENT_ID>",
    "token": "<YOUR_TOKEN>"
  }'

Replace the old JWT with the new one from the response and retry
the failed request.

** Step 3 — Verify **
Try calling any authenticated endpoint (e.g. list mandates) with
your JWT to confirm everything works:

curl https://walletapi.fluxapay.xyz/api/mandates \
  -H "Authorization: Bearer $JWT_TOKEN"

If you get a valid response, your Agent ID is ready. If the
response says the agent is not authorized, ask the user to open
the authorizationUrl to grant wallet access.