Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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:

Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9…

Proxima does not handle passwords. Users sign in with Turnkey, using an email code, a passkey or a wallet signature. The Turnkey session is then exchanged for a Proxima token.

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 (or POST /auth/email/resolve-org 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. The first exchange creates the account.

    Terminal window
    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, which returns a new token for the same session.

    Terminal window
    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.

KindHow you get itWhat it can callRefused with
BasePOST /auth/exchange, when the account has no license or severalAccount 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
UpgradedPOST /auth/upgrade, or POST /auth/exchange when the account owns exactly one active licenseEvery endpoint not marked Admin JWT, within the rights of its license.403 forbidden (admin role required) on admin endpoints
Read-onlyIssued by Proxima operators for support and auditsGET requests only, on the same endpoints as its kind.403 read_only_token on POST, PUT, PATCH and DELETE
AdminAn upgraded token of an account with the admin roleEvery endpoint, including those marked Admin JWT: the Admin 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, in a Requirements box under its summary.

Public endpoints

These endpoints need no token:

EndpointPurpose
GET /healthReachability and server time.
POST /auth/exchangeTrade a Turnkey session for a Proxima token.
POST /auth/wallet/resolve-orgFind the Turnkey sub-organization of a wallet.
POST /auth/email/resolve-orgFind the Turnkey sub-organization of an email.
POST /license/signupCreate a license for a new account.
GET /license/validate-license-keyCheck that a license key exists and is active.
GET /.well-known/jwks.jsonPublic 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.

TaskEndpoint
Validate a stored token at startupGET /auth/me
List the account’s active sessionsGET /auth/sessions
Sign out a devicePOST /auth/sessions/{session_id}/revoke

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 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 each time you connect or reconnect; see WebSocket channels.

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.