docs
Get startedTroubleshootingPaymentsWebhooksAgent paymentsSwop MCPOviIdentity (swop.id)SwivyRPC (preview)API reference
API reference

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

POST/v1/runtime/auth/email/request

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.

FieldTypeRequiredDescription
emailstringYes
externalUserIdstringNo

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

POST/v1/runtime/auth/email/verify

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.

FieldTypeRequiredDescription
emailstringYes
codestringYes
externalUserIdstringNo

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

POST/v1/runtime/auth/oidc/exchange

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.

FieldTypeRequiredDescription
tokenstringYes

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

POST/v1/runtime/auth/wallet/request

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.

FieldTypeRequiredDescription
chainstringYesAllowed: evm, solana
addressstringYes
connectorTypestringNoWallet connector label such as injected, privy, coinbase, or phantom.
externalUserIdstringNoOptional 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

POST/v1/runtime/auth/wallet/verify

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.

FieldTypeRequiredDescription
challengeIdstringYes
chainstringYesAllowed: evm, solana
addressstringYes
signaturestringYesEVM 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

POST/v1/runtime/auth/passkeys/signup/start

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

POST/v1/runtime/auth/passkeys/signup/finish

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)

POST/v1/runtime/auth/passkeys/login/start

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

POST/v1/runtime/auth/passkeys/login/verify

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

POST/v1/runtime/auth/sms/request

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

POST/v1/runtime/auth/sms/verify

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

On this page