- API Reference
- Getting Started
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
-
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(orPOST /auth/email/resolve-orgfor email) to find the Turnkey sub-organization to sign into. Both are public. -
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, thesession_id, the session expiry and the account’slicenses. -
Bind the token to a license. If the account owns exactly one active license, the token is already bound and
license_keyis set. Otherwise pick a license fromlicensesand callPOST /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>" }' -
Call the API. Send the upgraded token in the
Authorizationheader 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 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:
| 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 |
| List the account’s active sessions | GET /auth/sessions |
| Sign out a device | POST /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.