# Auth & step-up (/docs/swivy/api-reference/auth)

<Callout type="warn" title="Testnet preview">
Staging uses software custody. Use your environment’s API base URL and test assets only.
</Callout>

11 operations from the November 1, 2026 deployed contract. [Full OpenAPI schema](/swivy/openapi.json) · [Live interactive reference](https://swivy.swopme.co/docs#reference).

## Request an email login code [#request-an-email-login-code]

<EndpointHeader method="POST" path="/v1/runtime/auth/email/request" base={false} />

**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](/swivy/openapi.json).

**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 [#verify-an-email-login-code-and-create-a-runtime-session]

<EndpointHeader method="POST" path="/v1/runtime/auth/email/verify" base={false} />

**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](/swivy/openapi.json).

**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 [#exchange-a-swivy-oidc-token-for-a-runtime-session-in-another-environment]

<EndpointHeader method="POST" path="/v1/runtime/auth/oidc/exchange" base={false} />

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](/swivy/openapi.json).

**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 [#request-a-wallet-login-challenge]

<EndpointHeader method="POST" path="/v1/runtime/auth/wallet/request" base={false} />

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](/swivy/openapi.json).

**Responses:** `200` Wallet login challenge · `401` Missing or invalid environment credentials

## Verify a wallet-login signature and create a runtime session [#verify-a-wallet-login-signature-and-create-a-runtime-session]

<EndpointHeader method="POST" path="/v1/runtime/auth/wallet/verify" base={false} />

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](/swivy/openapi.json).

**Responses:** `200` Runtime session and profile · `401` Invalid wallet signature or environment credentials

## Start a passkey-only signup [#start-a-passkey-only-signup]

<EndpointHeader method="POST" path="/v1/runtime/auth/passkeys/signup/start" base={false} />

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](/swivy/openapi.json).

**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 [#finish-a-passkey-only-signup-and-get-a-session]

<EndpointHeader method="POST" path="/v1/runtime/auth/passkeys/signup/finish" base={false} />

**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](/swivy/openapi.json).

**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) [#start-a-passkey-login-discoverable-credential]

<EndpointHeader method="POST" path="/v1/runtime/auth/passkeys/login/start" base={false} />

**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](/swivy/openapi.json).

**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 [#verify-a-passkey-login-and-get-a-session]

<EndpointHeader method="POST" path="/v1/runtime/auth/passkeys/login/verify" base={false} />

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](/swivy/openapi.json).

**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 [#send-an-sms-login-code]

<EndpointHeader method="POST" path="/v1/runtime/auth/sms/request" base={false} />

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](/swivy/openapi.json).

**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 [#verify-an-sms-login-code-and-get-a-session]

<EndpointHeader method="POST" path="/v1/runtime/auth/sms/verify" base={false} />

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](/swivy/openapi.json).

**Responses:** `200` Result · `401` Invalid credentials or code · `404` Challenge not found · `410` Challenge expired or already used · `429` Too many attempts or requests
