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.
• Update the name — use the login JWT to change the agent's display name.
• 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/update	Update the authenticated agent's display name
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. A VC may also include optional Wallet ownership claims for the agent's authorized owner.

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.

With the CLI

The FluxA Wallet CLI registers the Agent ID, stores agent_id, token and jwt locally, and refreshes the JWT automatically:

fluxa-wallet status                                       # already configured?
fluxa-wallet init --name "My Trading Agent" --client "trading-bot-v1"
fluxa-wallet link-wallet                                  # user opens the URL to authorize
fluxa-wallet check-wallet                                 # linked: true when done