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.
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.
Attributes
-
idstringSession id (UUID). -
is_currentbooleanWhether this is the session of the token making the request. -
ipstring | nullIP address the session was created from. -
countrystring | nullCountry resolved from the IP. -
regionstring | nullRegion resolved from the IP. -
citystring | nullCity resolved from the IP. -
user_agentstring | nullUser agent of the client that created the session. -
activebooleanWhether the session is still valid. -
created_atintegerCreation time, in Unix seconds. -
updated_atintegerLast update time, in Unix seconds. -
last_used_atinteger | nullLast request made with the session, in Unix seconds. -
expires_atintegerExpiry time, in Unix seconds. -
labelstring | nullLabel of the session, when one was set.
Exchange a Turnkey token
/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_jwtstring RequiredTurnkey session JWT. It is the credential for this call.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
tokenstringProxima JWT to send asAuthorization: Bearer <token>. -
session_idstringId of the new session. -
user_idstringProxima user id. -
rolestringRole of the user:PUBLICorADMIN. -
expires_atintegerSession expiry, in Unix seconds. -
licensesarray<object>Licenses owned by the account, as License summary objects. -
license_keystring | nullLicense the token is bound to when it was upgraded automatically, elsenull.
Errors
| Status | Code | When 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
Upgrade a session token
/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_keystring RequiredLicense to bind the token to.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
tokenstringUpgraded Proxima JWT. -
license_keystringLicense the token is bound to. -
rolestringRole of the user:PUBLICorADMIN. -
expires_atintegerToken expiry, in Unix seconds. Equal to the session expiry.
Errors
| Status | Code | When 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
Retrieve the current session
/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_idstringProxima user id. -
turnkey_user_idstringTurnkey user id. -
rolestringRole of the user:PUBLICorADMIN. -
session_idstringId of the current session. -
license_keystring | nullLicense the token is bound to, ornullfor 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
/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
-
tokenstringCentrifugo 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
/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
-
sessionsarray<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
/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_idstring RequiredId (UUID) of the session to revoke.Examplec4f7a2d9-1e6b-4a83-9f5c-2d8e0b7a3c61
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
session_idstringId of the revoked session.
Errors
| Status | Code | When 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
Retrieve the signing keys
/.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
-
keysarray<object>Signing keys.Child attributes 7
-
ktystringKey type,EC. -
crvstringCurve,P-256. -
algstringAlgorithm,ES256. -
usestringKey use,sig. -
kidstringKey id, matched against thekidheader of a token. -
xstringBase64url X coordinate. -
ystringBase64url Y coordinate.
-
Errors
Only the common errors: 429 when rate limited.
Web client proxima.auth.getJwks() src/lib/proxima/endpoints/auth.ts
Resolve a wallet's organization
/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_addressstring OptionalWallet address:0xaddress on EVM, base58 on Solana. Preferred, as it needs no signature. -
public_keystring OptionalLowercase hex public key, used whenwallet_addressis not sent.
Returns 200 OK · application/json
-
foundbooleanWhether the wallet is linked to an account. -
sub_org_idstringTurnkey sub-organization id. Present only whenfoundistrue.
Errors
| Status | Code | When 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
Resolve an email's organization
/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
-
emailstring RequiredEmail address.
Returns 200 OK · application/json
-
foundbooleanWhether an account uses this email. -
sub_org_idstringTurnkey sub-organization id. Present only whenfoundistrue.
Errors
| Status | Code | When 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
Register a wallet authenticator
/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_keystring RequiredPublic key of the wallet authenticator. -
sub_org_idstring RequiredTurnkey sub-organization of the current user. -
wallet_addressstring RequiredWallet address. EVM addresses are stored lowercased. -
chainenum RequiredWallet type.Possible valuesevmsolana -
is_primaryboolean Optionaltruefor the wallet used at signup,falsefor wallets added later.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
insertedbooleanfalsewhen the wallet was already registered for this user.
Errors
| Status | Code | When 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
Unregister a wallet authenticator
/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_keystring RequiredPublic key of the wallet authenticator.
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
deletedbooleanWhether a registration was removed.
Errors
| Status | Code | When 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