# Authentication

> Exchange a Turnkey login for a Proxima session token, bind it to a license and manage sessions.

Proxima delegates login to Turnkey (email code, passkey or wallet). The client sends the Turnkey session JWT to `POST /auth/exchange`, which opens a Proxima session and returns a JWT. That token is a **base** token, unless the account owns exactly one active license, in which case it is already **upgraded**.

A base token only works on the `/auth/*` and `/2fa/*` routes. Every other route needs an upgraded token bound to a license key: call `POST /auth/upgrade` with one of the account's [licenses](/reference/licenses/) to get one. Both kinds of token share the same session, which lasts 7 days and can be listed and revoked.

The wallet routes keep Proxima's index of wallet authenticators in step with Turnkey, so a wallet can be resolved to its Turnkey sub-organization before the user signs in.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `POST /auth/exchange`: Exchange a Turnkey token
- `POST /auth/upgrade`: Upgrade a session token
- `GET /auth/me`: Retrieve the current session
- `GET /auth/ws-token`: Create a realtime connection token
- `GET /auth/sessions`: List sessions
- `POST /auth/sessions/{session_id}/revoke`: Revoke a session
- `GET /.well-known/jwks.json`: Retrieve the signing keys
- `POST /auth/wallet/resolve-org`: Resolve a wallet's organization
- `POST /auth/email/resolve-org`: Resolve an email's organization
- `POST /auth/wallet/register`: Register a wallet authenticator
- `POST /auth/wallet/unregister`: Unregister a wallet authenticator

## The Session object

A login session of the account. Every token issued for it, base or upgraded, stops working once it is revoked or expired.

- `id` (string): Session id (UUID).
- `is_current` (boolean): Whether this is the session of the token making the request.
- `ip` (string | null): IP address the session was created from.
- `country` (string | null): Country resolved from the IP.
- `region` (string | null): Region resolved from the IP.
- `city` (string | null): City resolved from the IP.
- `user_agent` (string | null): User agent of the client that created the session.
- `active` (boolean): Whether the session is still valid.
- `created_at` (integer): Creation time, in Unix seconds.
- `updated_at` (integer): Last update time, in Unix seconds.
- `last_used_at` (integer | null): Last request made with the session, in Unix seconds.
- `expires_at` (integer): Expiry time, in Unix seconds.
- `label` (string | null): Label of the session, when one was set.

```json
{
  "id": "3f6c1a2e-8b4d-4c7a-9e21-5d0b7f8a6c13",
  "is_current": true,
  "ip": "203.0.113.42",
  "country": "FR",
  "region": "Ile-de-France",
  "city": "Paris",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0 Safari/537.36",
  "active": true,
  "created_at": 1793440800,
  "updated_at": 1793613000,
  "last_used_at": 1793613000,
  "expires_at": 1794045600
}
```

### Exchange a Turnkey token

`POST /auth/exchange`

Trades a Turnkey session JWT for a Proxima session token. (No auth)

- Token: None. This endpoint is public.
- Retry: Safe to retry. Each call opens a new session. A session whose token was lost expires on its own, or end it with [Revoke a session](/reference/authentication/#revoke-session).

Creates the user on first login, opens a session (recording IP, location and user agent) and returns the account's licenses. When the account owns exactly one license and it is active, the returned token is already upgraded and `license_key` is set; otherwise the token is a base token and the client picks a license, then calls [Upgrade a session token](#upgrade-token).

The web app calls this right after every Turnkey login.

#### Body parameters

- `turnkey_jwt` (string, required): Turnkey session JWT. It is the credential for this call.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `token` (string): Proxima JWT to send as `Authorization: Bearer <token>`.
- `session_id` (string): Id of the new session.
- `user_id` (string): Proxima user id.
- `role` (string): Role of the user: `PUBLIC` or `ADMIN`.
- `expires_at` (integer): Session expiry, in Unix seconds.
- `licenses` (array<object>): Licenses owned by the account, as [License summary](/reference/licenses/#object-license-summary) objects.
- `license_key` (string | null): License the token is bound to when it was upgraded automatically, else `null`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 401 | `unauthorized` | `turnkey jwt expired` | The Turnkey JWT has expired. | Log in with Turnkey again and send the new session JWT. |
| 401 | `unauthorized` | `turnkey jwt signature verification failed` | The Turnkey JWT signature does not verify. A malformed JWT gets the same status with a message starting with `invalid turnkey jwt`. | Send the session JWT exactly as Turnkey returned it. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/exchange" \
  -H "Content-Type: application/json" \
  -d '{
  "turnkey_jwt": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiZTFiN2M1YTMifQ.ZXhhbXBsZS1zaWduYXR1cmU"
}'
```

#### Example response

```json
{
  "ok": true,
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzZjZjMWEyZS04YjRkLTRjN2EtOWUyMS01ZDBiN2Y4YTZjMTMifQ.dGhpcy1pcy1ub3QtYS1yZWFsLXNpZ25hdHVyZQ",
  "session_id": "3f6c1a2e-8b4d-4c7a-9e21-5d0b7f8a6c13",
  "user_id": "a91d4e70-2c3b-4f6e-8d15-7b9c0e2f4a68",
  "role": "PUBLIC",
  "expires_at": 1794218400,
  "license_key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "licenses": [
    {
      "key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
      "account_id": "5e2b8c41-7d9a-4e3f-b6c0-1a4d7f9e2b35",
      "username": "nova",
      "display_name": "Nova",
      "avatar_url": "https://cdn.example.com/profile-avatars/2f9c4e1a.png",
      "banner_url": null,
      "banner_theme": "orbit",
      "tier": "pro",
      "is_active": true
    }
  ]
}
```

### Upgrade a session token

`POST /auth/upgrade`

Issues a token bound to one license of the session. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Only issues a new token for the same session.

Accepts a base or an upgraded token. Regular users can only upgrade to a license they own; admins can upgrade to any active license, which the admin "Connect as" action relies on. The new token expires with the session.

The web app calls this after the user picks a license at login, after signup, and when switching license.

#### Body parameters

- `license_key` (string, required): License to bind the token to.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `token` (string): Upgraded Proxima JWT.
- `license_key` (string): License the token is bound to.
- `role` (string): Role of the user: `PUBLIC` or `ADMIN`.
- `expires_at` (integer): Token expiry, in Unix seconds. Equal to the session expiry.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid license_key format` | The license key format is invalid. | Send a key returned by [List the account's licenses](/reference/licenses/#list-account-licenses). |
| 403 | `forbidden` | `license_key is inactive` | The license is inactive. | Upgrade onto another license from [List the account's licenses](/reference/licenses/#list-account-licenses). |
| 403 | `forbidden` | `license_key does not belong to this user` | The license does not belong to the caller. Admins can upgrade onto any license. | Associate the license first with [Associate a license](/reference/licenses/#associate-license). |
| 404 | `not_found` | `license_key not found` | The license key does not exist. | Send a key returned by [List the account's licenses](/reference/licenses/#list-account-licenses). |

#### Example request

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

#### Example response

```json
{
  "ok": true,
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzZjZjMWEyZS04YjRkLTRjN2EtOWUyMS01ZDBiN2Y4YTZjMTMifQ.dGhpcy1pcy1ub3QtYS1yZWFsLXNpZ25hdHVyZQ",
  "license_key": "NOVA-x7Kp2QmZr9Tb4Lw8E",
  "role": "PUBLIC",
  "expires_at": 1794218400
}
```

### Retrieve the current session

`GET /auth/me`

Returns the user, session and license behind the current token. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Works with base and upgraded tokens. The web app calls it at startup to validate a stored token; if the call fails, it clears the stored session.

#### Returns 200 OK

- `user_id` (string): Proxima user id.
- `turnkey_user_id` (string): Turnkey user id.
- `role` (string): Role of the user: `PUBLIC` or `ADMIN`.
- `session_id` (string): Id of the current session.
- `license_key` (string | null): License the token is bound to, or `null` for a base token.

#### Example request

```bash
curl "https://api-mig.proxima.tools/auth/me" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "user_id": "a91d4e70-2c3b-4f6e-8d15-7b9c0e2f4a68",
  "turnkey_user_id": "e1b7c5a3-9d2f-4b6e-8c4a-3f7d1e9b5a20",
  "role": "PUBLIC",
  "session_id": "3f6c1a2e-8b4d-4c7a-9e21-5d0b7f8a6c13",
  "license_key": "NOVA-x7Kp2QmZr9Tb4Lw8E"
}
```

### Create a realtime connection token

`GET /auth/ws-token`

Returns a short-lived Centrifugo connection token for the session's account. (Bearer JWT · web client only)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The realtime client requests a fresh token each time it connects or reconnects to the Centrifugo websocket.

#### Returns 200 OK

- `token` (string): Centrifugo connection JWT. The SDK method returns this string directly.

#### Example request

```bash
curl "https://api-mig.proxima.tools/auth/ws-token" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIzZjZjMWEyZS04YjRkLTRjN2EtOWUyMS01ZDBiN2Y4YTZjMTMifQ.dGhpcy1pcy1ub3QtYS1yZWFsLXNpZ25hdHVyZQ"
}
```

### List sessions

`GET /auth/sessions`

Lists the sessions of the current account. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The Sessions settings page uses this list to show active devices and to revoke them.

#### Returns 200 OK

- `sessions` (array<object>): List of [Session](#object-session) objects.

#### Example request

```bash
curl "https://api-mig.proxima.tools/auth/sessions" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "sessions": [
    {
      "id": "3f6c1a2e-8b4d-4c7a-9e21-5d0b7f8a6c13",
      "is_current": true,
      "ip": "203.0.113.42",
      "country": "FR",
      "region": "Ile-de-France",
      "city": "Paris",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0 Safari/537.36",
      "active": true,
      "created_at": 1793440800,
      "updated_at": 1793613000,
      "last_used_at": 1793613000,
      "expires_at": 1794045600
    }
  ]
}
```

### Revoke a session

`POST /auth/sessions/{session_id}/revoke`

Ends one session of the current account. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Revoking a session that is already revoked succeeds again. If it was the session you are calling with, the retry fails with `401 invalid_session`, which confirms the revocation.

Every token issued for the session stops working. The web app revokes the current session on logout, and revokes other sessions from the Sessions settings page; "revoke all" sends one request per session.

> Revocation is immediate and cannot be undone. The user must log in again on that device.

#### Path parameters

- `session_id` (string, required): Id (UUID) of the session to revoke.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `session_id` (string): Id of the revoked session.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `session not found` | No session with this id belongs to the caller. | Use an id from [List sessions](/reference/authentication/#list-sessions). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/sessions/c4f7a2d9-1e6b-4a83-9f5c-2d8e0b7a3c61/revoke" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "session_id": "c4f7a2d9-1e6b-4a83-9f5c-2d8e0b7a3c61"
}
```

### Retrieve the signing keys

`GET /.well-known/jwks.json`

Returns the public keys that verify Proxima JWTs. (No auth)

- Token: None. This endpoint is public.
- Retry: Safe to retry.

A standard JWKS document. Proxima tokens are signed with ES256 (P-256).

> Not called by the current web app.

#### Returns 200 OK

- `keys` (array<object>): Signing keys.
  - `kty` (string): Key type, `EC`.
  - `crv` (string): Curve, `P-256`.
  - `alg` (string): Algorithm, `ES256`.
  - `use` (string): Key use, `sig`.
  - `kid` (string): Key id, matched against the `kid` header of a token.
  - `x` (string): Base64url X coordinate.
  - `y` (string): Base64url Y coordinate.

#### Example request

```bash
curl "https://api-mig.proxima.tools/.well-known/jwks.json"
```

#### Example response

```json
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "use": "sig",
      "kid": "px-2026-10",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
    }
  ]
}
```

### Resolve a wallet's organization

`POST /auth/wallet/resolve-org`

Finds the Turnkey sub-organization a wallet authenticator belongs to. (No auth)

- Token: None. This endpoint is public.
- Retry: Safe to retry.

Send `wallet_address` or `public_key`. The login page calls this before a wallet login to pass the sub-organization to Turnkey. The Connections settings call it before linking a wallet, to refuse one already linked to another Proxima account.

#### Body parameters

- `wallet_address` (string, optional): Wallet address: `0x` address on EVM, base58 on Solana. Preferred, as it needs no signature.
- `public_key` (string, optional): Lowercase hex public key, used when `wallet_address` is not sent.

#### Returns 200 OK

- `found` (boolean): Whether the wallet is linked to an account.
- `sub_org_id` (string): Turnkey sub-organization id. Present only when `found` is `true`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `wallet_address or public_key required` | Neither `wallet_address` nor `public_key` was sent. | Send the wallet address, or the public key of the wallet authenticator. |
| 429 | `too_many_requests` | `rate limit exceeded for resolve_wallet_org, please retry later` | More than 30 lookups per minute from the same IP. | Wait a minute before looking up again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/wallet/resolve-org" \
  -H "Content-Type: application/json" \
  -d '{
  "wallet_address": "7xKQm3vR9pTn2LcW8fYbHs4dJ6gA5uE1zNqXwVy2Bk3P"
}'
```

#### Example response

```json
{
  "found": true,
  "sub_org_id": "7d3e9b2a-4c1f-4e8d-a6b5-0f2c9e7d1a34"
}
```

### Resolve an email's organization

`POST /auth/email/resolve-org`

Finds the Turnkey sub-organization an email login belongs to. (No auth)

- Token: None. This endpoint is public.
- Retry: Safe to retry.

Emails are compared case-insensitively, so a differently-cased address logs into the existing account instead of creating a duplicate. The login page calls this before an email code login.

#### Body parameters

- `email` (string, required): Email address.

#### Returns 200 OK

- `found` (boolean): Whether an account uses this email.
- `sub_org_id` (string): Turnkey sub-organization id. Present only when `found` is `true`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `email required` | `email` is empty. | Send the email address the user signs in with. |
| 429 | `too_many_requests` | `rate limit exceeded for resolve_email_org, please retry later` | More than 30 lookups per minute from the same IP. | Wait a minute before looking up again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/email/resolve-org" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane@example.com"
}'
```

#### Example response

```json
{
  "found": false
}
```

### Register a wallet authenticator

`POST /auth/wallet/register`

Adds a wallet authenticator to Proxima's wallet index for the current user. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Registering a wallet already linked to the caller succeeds with `inserted: false`.

The Connections settings call this when the user adds a wallet as a login method, before creating the matching Turnkey API key. Registering a wallet the caller already registered succeeds with `inserted: false`.

#### Body parameters

- `public_key` (string, required): Public key of the wallet authenticator.
- `sub_org_id` (string, required): Turnkey sub-organization of the current user.
- `wallet_address` (string, required): Wallet address. EVM addresses are stored lowercased.
- `chain` (enum, required): Wallet type. Possible values: `evm`, `solana`.
- `is_primary` (boolean, optional, default "false"): `true` for the wallet used at signup, `false` for wallets added later.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `inserted` (boolean): `false` when the wallet was already registered for this user.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `public_key required` | A field is empty: `public_key`, `sub_org_id` or `wallet_address`. The message names the first empty one, for example `sub_org_id required`. | Send every field with a non-empty value. |
| 400 | `bad_request` | `chain must be 'evm' or 'solana'` | `chain` is not `evm` or `solana`. | Send `evm` or `solana`. |
| 409 | `conflict` | `this wallet is already linked to another account` | The wallet is already linked to another account. | Unregister it from the other account first, or use another wallet. |
| 429 | `too_many_requests` | `rate limit exceeded for register_wallet, please retry later` | More than 20 registrations per minute for the user. | Wait a minute before registering again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/wallet/register" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "public_key": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc",
  "sub_org_id": "7d3e9b2a-4c1f-4e8d-a6b5-0f2c9e7d1a34",
  "wallet_address": "0x8f3c2a91d4e7b6058c1f9a2e3d4b5c6a7e8f9012",
  "chain": "evm",
  "is_primary": false
}'
```

#### Example response

```json
{
  "ok": true,
  "inserted": true
}
```

### Unregister a wallet authenticator

`POST /auth/wallet/unregister`

Removes a wallet authenticator of the current user from the wallet index. (Bearer JWT)

- Token: Base or upgraded session token.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Removing a wallet that is no longer linked succeeds with `deleted: false`.

Called after the matching Turnkey API key is deleted. A wallet that is not registered returns `deleted: false` instead of an error, so retries are safe.

#### Body parameters

- `public_key` (string, required): Public key of the wallet authenticator.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `deleted` (boolean): Whether a registration was removed.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `public_key required` | `public_key` is empty. | Send the public key of the wallet authenticator to remove. |
| 429 | `too_many_requests` | `rate limit exceeded for unregister_wallet, please retry later` | More than 20 removals per minute for the user. | Wait a minute before trying again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/auth/wallet/unregister" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "public_key": "02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc"
}'
```

#### Example response

```json
{
  "ok": true,
  "deleted": true
}
```
