Authentication
Every request carries your API key. Requests about a user also carry that user's session token:
| Header | What it is |
|---|---|
X-Api-Key: fin_… | Your API key. Identifies your app. Keep it on your server. |
Authorization: Bearer fin_session_… | A user's session token, from Create a session. |
A few calls need only the API key: Create a user, Start wallet sign-in, Create a session, Get your AI usage and Get your rate limits.
API keys
Your deployment operator issues your keys. A key is shown once, when it is created, and can carry an expiry. To rotate one, get a new key, switch your backend to it, then have the old one revoked; a revoked key can keep working for up to 30 seconds. Never put an API key in browser code, a URL or a public repository.
Sign a user in
Create the user once with Create a user (POST /v1/users, body {userId, name}). Then open a session for them whenever they use your app, in one of two ways:
- Your app has its own login. After your login verifies the user, call
POST /v1/users/{userId}/sessionswith{"controller": …}: the wallet or passkey they signed in with. Your API key vouches for them, so they sign nothing extra. - Your app has no login. Call Start wallet sign-in for the user's wallet, have them sign the returned
messageexactly as it is, and send{challengeId, signature}toPOST /v1/users/{userId}/sessions.
Either way you get a token. Sessions last one hour and cannot be refreshed. A request with an expired token answers 401 with reason credential_expired: create another session the same way. A 401 with no reason means the token was revoked or was never valid. Revoke the session when the user logs out of your app. Logging out deletes nothing and does not stop work already started.
The first session registers the user's wallet (their controller) for good. Every later session must name the same wallet, and that wallet signs everything that moves money. Only vouch for users your login has really verified, with the wallet they really used.
If your app proxies browser requests, allow only the user operations the browser needs, require its verified session, and bind any {userId} path to that session. Never attach your API key to arbitrary browser-selected Fin paths: even a signed-in user must not call partner-only enrollment, session issuance, provider-session or partner usage operations. Provision and vouch inside your trusted login handler, deriving the user and controller from the login it verified rather than from a browser-supplied identity.
Supported wallets
| Wallet | controller | signature | How the wallet signs |
|---|---|---|---|
| EVM | {kind: "evm", chainId, address} | {kind: "evm", signature} (0x, 65 bytes) | ERC-191 personal message signing |
| NEAR | {kind: "near", accountId} | {kind: "near", publicKey, signature, nonce} | NEP-413 signMessage({message, recipient, nonce}) with the recipient the API returns and 32 random bytes as nonce |
| Solana | {kind: "solana", address} | {kind: "solana", signature} | signMessage over the UTF-8 bytes |
| Stellar | {kind: "stellar", address} | {kind: "stellar", signature} | SEP-53 message signing |
| TON | {kind: "ton", publicKey} | {kind: "ton", signature, address, domain, timestamp} | TON Connect signData({type: "text", text: message}), domain one of your registered origins' hosts |
| Tron | {kind: "tron", address} | {kind: "tron", signature} (0x, 65 bytes) | TIP-191 signMessageV2 |
| Passkey | {kind: "webauthn", credentialId, publicKey, rpId, origin} | the WebAuthn assertion | a P-256 or Ed25519 assertion whose challenge is the SHA-256 of the message |
Ed25519 signatures are 64 bytes in padded standard base64. A NEAR account must sign with one of its current full-access keys. A passkey must belong to one of your registered origins.
Security model
Three things authorize three different kinds of action:
| Credential | Lets you | Cannot |
|---|---|---|
| API key | Create users, open sessions, read your usage | Read or act for a user without their session |
| Session token | Everything a signed-in user can do: chat, start and cancel runs, read history, manage automations | Move money or create the agent wallet |
| The user's signature | Create the agent wallet, withdraw, swap, place a limit order, approve a trade | Anything other than the one request it signs |
| An agent 1Click session, from Get a 1Click session | Read the agent wallet at 1Click: balances, history and orders; cancel its open orders | Move funds: every withdrawal, swap, order and trade still needs the user's signature |
Money only moves with the user's signature over that exact request, or within limits the user signed for an automation ahead of time. The API gives you the message to sign each time; show the user what it covers before they sign. A signature is valid for about five minutes and works once.
Keep the API key and session tokens on your server (or in HttpOnly cookies) and proxy browser requests through your backend; never put them in browser JavaScript, URLs or local storage. The same goes for an agent's 1Click tokens. Fin cannot revoke those once it has issued them: each lasts until its refreshTokenExpiresAt, so delete them when the user signs out. Fin never calls your servers, so read a resource again (or follow the event stream) to see changes, with a live session.