Auth & step-up
Current Swivy API operations from the deployed OpenAPI snapshot.
Testnet preview
Staging uses software custody. Use your environment’s API base URL and test assets only.
11 operations from the November 1, 2026 deployed contract. Full OpenAPI schema · Live interactive reference.
Request an email login code
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Email login payload
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | |
externalUserId | string | No |
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Login code issued · 401 Missing or invalid environment credentials · 502 Email delivery failed
Verify an email login code and create a runtime session
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Email verification payload
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | |
code | string | Yes | |
externalUserId | string | No |
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Runtime session and profile · 401 Invalid email code or environment credentials
Exchange a Swivy OIDC token for a runtime session in another environment
Use this when another app signs the user in with Swop and then needs a normal Swivy runtime session plus managed wallets in its own environment.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. OIDC token exchange payload
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes |
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Runtime session and profile · 401 Invalid OIDC token or environment credentials · 403 OIDC token is outside the current project boundary
Request a wallet-login challenge
Creates a short-lived Swivy login challenge for an external EVM or Solana wallet. The app must ask the connected wallet to sign the returned message exactly.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Wallet login request payload
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
chain | string | Yes | Allowed: evm, solana |
address | string | Yes | |
connectorType | string | No | Wallet connector label such as injected, privy, coinbase, or phantom. |
externalUserId | string | No | Optional customer-side stable user identifier to attach to the Swivy identity. |
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Wallet login challenge · 401 Missing or invalid environment credentials
Verify a wallet-login signature and create a runtime session
Verifies that the external wallet controls the requested address, links that wallet to the Swivy identity, records a wallet auth method, and returns the normal runtime session payload.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Wallet login verification payload
Content type: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
challengeId | string | Yes | |
chain | string | Yes | Allowed: evm, solana |
address | string | Yes | |
signature | string | Yes | EVM personal_sign signature, or Solana signature encoded as base58 or base64. |
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Runtime session and profile · 401 Invalid wallet signature or environment credentials
Start a passkey-only signup
Returns WebAuthn registration options. The new account has no email.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Request
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Result · 401 Invalid credentials or code · 404 Challenge not found · 410 Challenge expired or already used · 429 Too many attempts or requests
Finish a passkey-only signup and get a session
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Request
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Result · 401 Invalid credentials or code · 404 Challenge not found · 410 Challenge expired or already used · 429 Too many attempts or requests
Start a passkey login (discoverable credential)
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Request
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Result · 401 Invalid credentials or code · 404 Challenge not found · 410 Challenge expired or already used · 429 Too many attempts or requests
Verify a passkey login and get a session
Works for passkeys created at signup or enrolled as MFA.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Request
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Result · 401 Invalid credentials or code · 404 Challenge not found · 410 Challenge expired or already used · 429 Too many attempts or requests
Send an SMS login code
5 sends per phone per 15 minutes. 403 when SMS delivery is disabled.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Request
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Result · 401 Invalid credentials or code · 404 Challenge not found · 410 Challenge expired or already used · 429 Too many attempts or requests
Verify an SMS login code and get a session
5 wrong codes lock the challenge. Logs into the account that verified this phone, or creates a phone-only account.
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key
Request body: required. Request
Content type: application/json.
See the full schema for this payload; the contract does not enumerate top-level fields here.
Nested schemas and constraints are in the OpenAPI document.
Responses: 200 Result · 401 Invalid credentials or code · 404 Challenge not found · 410 Challenge expired or already used · 429 Too many attempts or requests