# Authentication

> Sign in through Turnkey, exchange the session for a Proxima JWT, bind it to a license and send it on every request.

The Proxima API authenticates every request with a **session JWT** sent as a bearer token:

```http
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9…
```

Proxima does not handle passwords. Users sign in with [Turnkey](https://www.turnkey.com/), using an email code, a
passkey or a wallet signature. The Turnkey session is then exchanged for a Proxima token.

> **Danger:** A Proxima token can move funds, reveal private keys and change account settings. Keep it server-side, load it from
> an environment variable or a secret manager, and never commit it, log it or send it to a third party.

## Sign-in flow

1. **Sign in with Turnkey.** Complete an email, passkey or wallet login with Turnkey and keep the session JWT it
   returns. For a wallet login, first call [`POST /auth/wallet/resolve-org`](/reference/authentication/#resolve-wallet-organization)
   (or [`POST /auth/email/resolve-org`](/reference/authentication/#resolve-email-organization) for email) to find the
   Turnkey sub-organization to sign into. Both are public.

2. **Exchange it for a Proxima token.** Send the Turnkey JWT to
   [`POST /auth/exchange`](/reference/authentication/#exchange-token). The first exchange creates the account.

   ```bash
   curl -X POST https://api-mig.proxima.tools/auth/exchange \
     -H "Content-Type: application/json" \
     -d '{ "turnkey_jwt": "<turnkey-session-jwt>" }'
   ```

   The response contains the Proxima `token`, the `session_id`, the session expiry and the account's `licenses`.

3. **Bind the token to a license.** If the account owns exactly one active license, the token is already bound and
   `license_key` is set. Otherwise pick a license from `licenses` and call
   [`POST /auth/upgrade`](/reference/authentication/#upgrade-token), which returns a new token for the same session.

   ```bash
   curl -X POST https://api-mig.proxima.tools/auth/upgrade \
     -H "Authorization: Bearer $PROXIMA_JWT" \
     -H "Content-Type: application/json" \
     -d '{ "license_key": "<license_key>" }'
   ```

4. **Call the API.** Send the upgraded token in the `Authorization` header of every request. The examples in this
   reference read it from `$PROXIMA_JWT`.

## Token kinds

A session issues two kinds of token. Both are signed with ES256 and share the same expiry. Two restrictions can
apply on top of them: read-only access and the admin role.

| Kind | How you get it | What it can call | Refused with |
| --- | --- | --- | --- |
| **Base** | `POST /auth/exchange`, when the account has no license or several | Account endpoints only: `/auth/me`, `/auth/licenses*`, `/auth/sessions*`, `/auth/upgrade`, `/auth/wallet/register`, `/auth/wallet/unregister` and `/2fa/*`. | `401 license_required` on any other endpoint |
| **Upgraded** | `POST /auth/upgrade`, or `POST /auth/exchange` when the account owns exactly one active license | Every endpoint not marked **Admin JWT**, within the rights of its license. | `403 forbidden` (`admin role required`) on admin endpoints |
| **Read-only** | Issued by Proxima operators for support and audits | `GET` requests only, on the same endpoints as its kind. | `403 read_only_token` on `POST`, `PUT`, `PATCH` and `DELETE` |
| **Admin** | An upgraded token of an account with the admin role | Every endpoint, including those marked **Admin JWT**: the [Admin](/reference/admin-users/) group, launch scripts, the X tracker and support administration. | — |

A license can be switched at any time by calling `POST /auth/upgrade` again with another key.

Every endpoint in this reference states the token it needs, whether read-only tokens are accepted, and whether it
can ask for a [second factor](#sensitive-actions), in a **Requirements** box under its summary.

## Public endpoints

These endpoints need no token:

| Endpoint | Purpose |
| --- | --- |
| `GET /health` | Reachability and server time. |
| `POST /auth/exchange` | Trade a Turnkey session for a Proxima token. |
| `POST /auth/wallet/resolve-org` | Find the Turnkey sub-organization of a wallet. |
| `POST /auth/email/resolve-org` | Find the Turnkey sub-organization of an email. |
| `POST /license/signup` | Create a license for a new account. |
| `GET /license/validate-license-key` | Check that a license key exists and is active. |
| `GET /.well-known/jwks.json` | Public keys to verify Proxima tokens. |

## Sessions

A session lasts **7 days** from sign-in. `expires_at` in the exchange and upgrade responses is the expiry in epoch
seconds; plan to sign in again before it passes. The token cannot be refreshed past that point.

| Task | Endpoint |
| --- | --- |
| Validate a stored token at startup | [`GET /auth/me`](/reference/authentication/#retrieve-current-session) |
| List the account's active sessions | [`GET /auth/sessions`](/reference/authentication/#list-sessions) |
| Sign out a device | [`POST /auth/sessions/{session_id}/revoke`](/reference/authentication/#revoke-session) |

Once a session is revoked or expires, every token issued for it fails with `401 invalid_session`. The web app
signs the user out when it sees `invalid_session` or `invalid_token`; your integration should do the same.

## Verifying tokens

To verify a Proxima token in your own backend, fetch the public keys from
[`GET /.well-known/jwks.json`](/reference/authentication/#retrieve-jwks) and check the ES256 signature and the `exp`
claim. Cache the key set and refetch it when a token carries an unknown `kid`.

## Realtime token

The realtime WebSocket does not accept the session JWT directly. Request a short-lived connection token from
[`GET /auth/ws-token`](/reference/authentication/#create-realtime-token) each time you connect or reconnect; see
[WebSocket channels](/realtime/websocket/).

## Sensitive actions

Withdrawals, key exports, launch sharing and changes to security settings can require a second factor on top of
the token. The API answers `401 2fa_required` with a challenge; see
[Two-factor step-up](/getting-started/two-factor-step-up/).
