Authentication and Scopes

Machine authentication uses a Flare chain-14 EIP-4361 SIWE challenge. Sign the exact returned message with your wallet (EIP-191 personal_sign). The nonce is single-use, wallet-bound and expires after five minutes. Request only the permissions your client needs. The example asks for write and spend because the following topup and subscription examples use both; read is always included.

curl -X POST 'https://ftso.app/api/x402/auth/challenge' \
  -H 'content-type: application/json' \
  -d '{"wallet":"0xYOUR_WALLET","scopes":["write","spend"],"label":"My agent"}'

The response contains wallet, nonce, issuedAt and message. Preserve message exactly, including whitespace. In viem use account.signMessage({ message }). Scopes are part of the signed consent; a label is cosmetic metadata, at most 40 characters. Do not reconstruct the message from the nonce.

curl -X POST 'https://ftso.app/api/x402/auth/token' \
  -H 'content-type: application/json' \
  -d '{"message":"EXACT_RETURNED_SIWE_MESSAGE","signature":"0xSIGNATURE"}'
# Response: { token: "fbx_...", wallet, scopes, expiresAt }

Store token securely and send Authorization: Bearer fbx_… on subsequent calls. Do not put it in a query string, shared logs or examples. Token exchange is no-store. EOA signatures are verified locally; contract-wallet verification depends on the configured server RPC and rejects authentication on verification failure.

• read: reads and message previews; includes paid data access if enforcement is enabled.
• write: changes, recipient tests, topup drafts and confirmations, terms acceptance, trials and disabling auto-renew.
• spend: buying subscription capacity and enabling auto-renew.
• read is always granted, including with write or spend. A write token can revoke any token of the same wallet.

curl 'https://ftso.app/api/x402/auth/tokens' -H 'authorization: Bearer fbx_TOKEN'
curl -X DELETE 'https://ftso.app/api/x402/auth/tokens/42' \
  -H 'authorization: Bearer fbx_WRITE_TOKEN'

A wallet may have at most ten active tokens. Listing returns up to 50 metadata entries, active first; it never returns secrets or hashes. Revocation takes effect on the next authenticated request. Foreign IDs return 404. The browser can manage tokens in Wallet-Center Settings → Security. MCP uses its own OAuth flow; an x402 Bearer-Token is not an MCP access token.

• Bearer-token lifetime in seconds: 86400
• Anonymous free-tier calls per day (enforce only): 50