API essentials

Authentication

Every request carries your API key. Requests about a user also carry that user's session token:

HeaderWhat 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}/sessions with {"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 message exactly as it is, and send {challengeId, signature} to POST /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

WalletcontrollersignatureHow 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 assertiona 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:

CredentialLets youCannot
API keyCreate users, open sessions, read your usageRead or act for a user without their session
Session tokenEverything a signed-in user can do: chat, start and cancel runs, read history, manage automationsMove money or create the agent wallet
The user's signatureCreate the agent wallet, withdraw, swap, place a limit order, approve a tradeAnything other than the one request it signs
An agent 1Click session, from Get a 1Click sessionRead the agent wallet at 1Click: balances, history and orders; cancel its open ordersMove 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.

Fin documentation Built from the API contract · v1

Search all documentation