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.

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

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 '{
    "email": "agent@example.com",
    "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.