Skip to content
API Reference

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

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

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

Attributes

  • 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.
POST /auth/exchange

Trades a Turnkey session JWT for a Proxima session token.

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.

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.

The web app calls this right after every Turnkey login.

Body parameters application/json

  • turnkey_jwt string Required
    Turnkey session JWT. It is the credential for this call.

Returns 200 OK · application/json

  • 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 objects.
  • license_key string | null
    License the token is bound to when it was upgraded automatically, else null.

Errors

StatusCodeWhen and what to do
401 unauthorized The Turnkey JWT has expired. Log in with Turnkey again and send the new session JWT.
401 unauthorized 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.

Also the common errors: 429 when rate limited.

Web client proxima.auth.exchange({ turnkey_jwt }) src/lib/proxima/endpoints/auth.ts

POST /auth/upgrade

Issues a token bound to one license of the session.

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 application/json

  • license_key string Required
    License to bind the token to.

Returns 200 OK · application/json

  • 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

StatusCodeWhen and what to do
400 bad_request The license key format is invalid. Send a key returned by List the account's licenses.
403 forbidden The license is inactive. Upgrade onto another license from List the account's licenses.
403 forbidden The license does not belong to the caller. Admins can upgrade onto any license. Associate the license first with Associate a license.
404 not_found The license key does not exist. Send a key returned by List the account's licenses.

Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.

Web client proxima.auth.upgrade({ license_key }) src/lib/proxima/endpoints/auth.ts

GET /auth/me

Returns the user, session and license behind the current token.

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.

Parameters

No parameters.

Returns 200 OK · application/json

  • 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.

Errors

Only the common errors: 401 for a missing or expired session and 429 when rate limited.

Web client proxima.auth.me() src/lib/proxima/endpoints/auth.ts

GET /auth/ws-token

Returns a short-lived Centrifugo connection token for the session's account.

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.

Parameters

No parameters.

Returns 200 OK · application/json

  • token string
    Centrifugo connection JWT. The SDK method returns this string directly.

Errors

Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.auth.wsToken() src/lib/proxima/endpoints/auth.ts

List sessions

Bearer JWT
GET /auth/sessions

Lists the sessions of the current account.

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.

Parameters

No parameters.

Returns 200 OK · application/json

  • sessions array<object>
    List of Session objects.

Errors

Only the common errors: 401 for a missing or expired session and 429 when rate limited.

Web client proxima.auth.getSessions() src/lib/proxima/endpoints/auth.ts

Revoke a session

Bearer JWT
POST /auth/sessions/{session_id}/revoke

Ends one session of the current account.

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.

Path parameters

  • session_id string Required
    Id (UUID) of the session to revoke.
    Examplec4f7a2d9-1e6b-4a83-9f5c-2d8e0b7a3c61

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • session_id string
    Id of the revoked session.

Errors

StatusCodeWhen and what to do
404 not_found No session with this id belongs to the caller. Use an id from List sessions.

Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.

Web client proxima.auth.revokeSession(sessionId) src/lib/proxima/endpoints/auth.ts

GET /.well-known/jwks.json

Returns the public keys that verify Proxima JWTs.

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

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

Parameters

No parameters.

Returns 200 OK · application/json

  • keys array<object>
    Signing keys.
    Child attributes 7
    • 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.

Errors

Only the common errors: 429 when rate limited.

Web client proxima.auth.getJwks() src/lib/proxima/endpoints/auth.ts

POST /auth/wallet/resolve-org

Finds the Turnkey sub-organization a wallet authenticator belongs to.

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 application/json

  • 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 · application/json

  • 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

StatusCodeWhen and what to do
400 bad_request Neither wallet_address nor public_key was sent. Send the wallet address, or the public key of the wallet authenticator.
429 too_many_requests More than 30 lookups per minute from the same IP. Wait a minute before looking up again.

Also the common errors: 429 when rate limited.

Web client proxima.auth.resolveWalletOrg({ wallet_address }) src/lib/proxima/endpoints/auth.ts

POST /auth/email/resolve-org

Finds the Turnkey sub-organization an email login belongs to.

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 application/json

  • email string Required
    Email address.

Returns 200 OK · application/json

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

Errors

StatusCodeWhen and what to do
400 bad_request email is empty. Send the email address the user signs in with.
429 too_many_requests More than 30 lookups per minute from the same IP. Wait a minute before looking up again.

Also the common errors: 429 when rate limited.

Web client proxima.auth.resolveEmailOrg({ email }) src/lib/proxima/endpoints/auth.ts

POST /auth/wallet/register

Adds a wallet authenticator to Proxima's wallet index for the current user.

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 application/json

  • 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 evmsolana
  • is_primary boolean Optional Default false
    true for the wallet used at signup, false for wallets added later.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • inserted boolean
    false when the wallet was already registered for this user.

Errors

StatusCodeWhen and what to do
400 bad_request 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 is not evm or solana. Send evm or solana.
409 conflict The wallet is already linked to another account. Unregister it from the other account first, or use another wallet.
429 too_many_requests More than 20 registrations per minute for the user. Wait a minute before registering again.

Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.

Web client proxima.auth.registerWallet(request) src/lib/proxima/endpoints/auth.ts

POST /auth/wallet/unregister

Removes a wallet authenticator of the current user from the wallet index.

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 application/json

  • public_key string Required
    Public key of the wallet authenticator.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • deleted boolean
    Whether a registration was removed.

Errors

StatusCodeWhen and what to do
400 bad_request public_key is empty. Send the public key of the wallet authenticator to remove.
429 too_many_requests More than 20 removals per minute for the user. Wait a minute before trying again.

Also the common errors: 401 for a missing or expired session, 403 read_only_token and 429 when rate limited.

Web client proxima.auth.unregisterWallet({ public_key }) src/lib/proxima/endpoints/auth.ts