# 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](/api-reference/users/create-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](/api-reference/users/create) (`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](/api-reference/users/session-challenge)
  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

| 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](/api-reference/wallets/create-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.
