Agent registration

POST/register↗

Register an agent to obtain credentials used by the HTTP APIs. Both request fields are optional; provide them when you want to label the agent or record the registering client.

On success, you receive:

• agent_id – unique identifier for the agent
• token – OAuth‑style secret (store securely)
• jwt – bearer token used when calling FluxA payment and payout endpoints

The endpoint returns 201 Created. The persistent token is shown only in this response, so store it before continuing.

Example:

curl -X POST https://agentid.fluxapay.xyz/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Your Agent Name",
    "client_info": "Your Client Info"
  }'

Response (201):

{
  "agent_id": "agent_01H8XABCDEF1234567890",
  "token": "<long random secret — shown once>",
  "jwt": "eyJhbGciOiJSUzI1NiIs...",
  "agent_name": "Your Agent Name",
  "message": "Save the token now. It will not be shown again."
}

The jwt is short-lived (minutes) and its payload carries only agent_id. Refresh it with /refresh when it expires.

To use payment, payout, mandate and payment-link APIs, the agent must also be linked to a user's FluxA Wallet. The first wallet API that needs it returns an authorizationUrl (for example create intent mandate) for the user to open.

Implementation tips:

• Persist agent_id, token, and jwt in a secure store and associate them with your user/agent record.
• Use the jwt in the Authorization: Bearer header for payment and payout calls.

---

Refresh JWT

POST/refresh↗

JWTs expire periodically. Call /refresh to obtain a fresh token using the agent_id and token from registration.

curl -X POST https://agentid.fluxapay.xyz/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "token": "your-token"
  }'

Response (200): { "jwt": "eyJ..." }. Replace the old JWT in your secure store and use it for subsequent API calls. The token does not change.

Status	Body	Meaning
400	{ "error": "agent_id and token required" }	Missing field.
401	{ "error": "invalid_token" }	token does not match this agent.
404	{ "error": "agent_not_found" }	Unknown agent_id.

---

Update agent name

POST/agent/updateBearer agent-jwt↗

Use the current login JWT to change the authenticated agent's display name. The service derives the agent_id from the JWT, so do not send it in the request body.

curl -X POST https://agentid.fluxapay.xyz/agent/update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOGIN_JWT" \
  -d '{ "agent_name": "Research Agent" }'

{
  "agent_id": "agent_01H8XABCDEF1234567890",
  "agent_name": "Research Agent",
  "message": "Agent updated."
}

Status	Body	Meaning
400	{ "error": "agent_name required" }	agent_name missing or not a string.
401	{ "error": "missing_bearer" } / invalid_or_expired_jwt	No or expired login JWT — call /refresh.
401	{ "error": "wrong_token_type" }	A VC was sent; use the login JWT.
404	{ "error": "agent_not_found" }	The agent no longer exists.