# OIDC & MCP (/docs/swivy/api-reference/oidc)

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

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

## Fetch the OIDC discovery document [#fetch-the-oidc-discovery-document]

<EndpointHeader method="GET" path="/oidc/{appId}/.well-known/openid-configuration" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Responses:** `200` OIDC discovery document · `404` Issuer environment not found

## Fetch the issuer JWKS [#fetch-the-issuer-jwks]

<EndpointHeader method="GET" path="/oidc/{appId}/jwks" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Responses:** `200` OIDC JWKS · `404` Issuer environment not found

## Request a hosted text-message login code [#request-a-hosted-text-message-login-code]

<EndpointHeader method="POST" path="/oidc/{appId}/login/sms/request" base={false} />

Requires a trusted browser origin and SMS enabled in both the environment login policy and this OIDC client.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Request body:** required. Hosted SMS login

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `clientId` | string | Yes |  |
| `phoneNumber` | string | Yes |  |

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Result · `401` Invalid code · `403` Origin or method not allowed · `404` Client, environment, or challenge not found · `410` Challenge expired or used · `429` Too many attempts or requests · `502` SMS delivery failed

## Verify a hosted text-message login code [#verify-a-hosted-text-message-login-code]

<EndpointHeader method="POST" path="/oidc/{appId}/login/sms/verify" base={false} />

Requires a trusted browser origin and SMS enabled in both the environment login policy and this OIDC client.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Request body:** required. Hosted SMS login

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `clientId` | string | Yes |  |
| `challengeId` | string | Yes |  |
| `code` | string | Yes |  |

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Result · `401` Invalid code · `403` Origin or method not allowed · `404` Client, environment, or challenge not found · `410` Challenge expired or used · `429` Too many attempts or requests · `502` SMS delivery failed

## Request an email code for the hosted OIDC login flow [#request-an-email-code-for-the-hosted-oidc-login-flow]

<EndpointHeader method="POST" path="/oidc/{appId}/login/email/request" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**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` Email code issued for OIDC login · `404` Issuer environment not found · `502` Verification email delivery failed

## Verify an email code and establish the hosted OIDC session [#verify-an-email-code-and-establish-the-hosted-oidc-session]

<EndpointHeader method="POST" path="/oidc/{appId}/login/email/verify" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**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 hosted OIDC session · `401` Invalid email code · `404` Issuer environment not found

## Request a wallet-login challenge for the hosted OIDC login flow [#request-a-wallet-login-challenge-for-the-hosted-oidc-login-flow]

<EndpointHeader method="POST" path="/oidc/{appId}/login/wallet/request" base={false} />

Used by the hosted Swivy login page to prove control of an external EVM or Solana wallet before continuing the OIDC authorize flow.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**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 · `404` Issuer environment not found

## Verify a wallet-login signature and establish the hosted OIDC session [#verify-a-wallet-login-signature-and-establish-the-hosted-oidc-session]

<EndpointHeader method="POST" path="/oidc/{appId}/login/wallet/verify" base={false} />

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**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 hosted OIDC session · `401` Invalid wallet signature · `404` Issuer environment not found

## Approve or deny the hosted OIDC consent prompt [#approve-or-deny-the-hosted-oidc-consent-prompt]

<EndpointHeader method="POST" path="/oidc/{appId}/authorize/consent" base={false} />

Used by the hosted Swivy authorize UI to record a consent decision and continue the authorization code flow.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Request body:** required. Hosted consent decision payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | Yes |  |
| `redirect_uri` | string | Yes |  |
| `scope` | string | Yes |  |
| `state` | string | No |  |
| `nonce` | string | No |  |
| `code_challenge` | string | No |  |
| `code_challenge_method` | string | No | Allowed: S256 |
| `decision` | string | Yes | Allowed: approve, deny |
| `remember` | boolean | No |  |

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` Consent decision redirect target · `400` Invalid consent request · `401` Login required · `404` Issuer environment not found

## End the hosted OIDC session [#end-the-hosted-oidc-session]

<EndpointHeader method="GET" path="/oidc/{appId}/logout" base={false} />

Clears the hosted Swivy OIDC session cookie and revokes the matching runtime session when one is present. Supports a post-logout redirect to a registered client redirect URI.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |
| `client_id` | query | No | OIDC client identifier |
| `post_logout_redirect_uri` | query | No | Registered redirect URI to return the browser to after logout |
| `state` | query | No | Opaque client state value echoed to the post-logout redirect |

**Responses:** `200` Hosted logout result or confirmation page · `302` Redirect to the validated post-logout callback URL · `400` Invalid logout request · `404` Issuer environment not found

## Run the OIDC authorization code flow [#run-the-oidc-authorization-code-flow]

<EndpointHeader method="GET" path="/oidc/{appId}/authorize" base={false} />

If a matching Swivy runtime session is not already present, this route can render the hosted email and wallet login page or return login_required. If login exists but consent is still required, it can render the hosted consent page or return consent_required.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |
| `response_type` | query | Yes | OIDC response type |
| `client_id` | query | Yes | OIDC client identifier |
| `redirect_uri` | query | Yes | Registered redirect URI |
| `scope` | query | Yes | Space-delimited scopes |
| `state` | query | No | Opaque client state value |
| `nonce` | query | No | Nonce echoed into the ID token |
| `code_challenge` | query | No | PKCE code challenge |
| `code_challenge_method` | query | No | PKCE code challenge method |
| `prompt` | query | No | OIDC prompt behavior |
| `login_hint` | query | No | Prefilled email address for the hosted login screen |
| `screen_hint` | query | No | Choose whether the hosted page defaults to login or signup copy |

**Responses:** `200` Hosted OIDC login page · `302` Redirect to the client callback with an authorization code or error · `400` Invalid authorize request or client · `401` Login required · `403` Consent required · `404` Issuer environment not found

## Exchange an authorization code for OIDC tokens [#exchange-an-authorization-code-for-oidc-tokens]

<EndpointHeader method="POST" path="/oidc/{appId}/token" base={false} />

Supports authorization_code and refresh_token grants plus public PKCE clients, client_secret_post, and client_secret_basic authentication.

**Auth:** No operation-level credentials specified; deployment and policy restrictions still apply.

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Request body:** required. OIDC token exchange payload

Content type: `application/json`.

| Field | Type | Required | Description |
|---|---|---|---|
| `grant_type` | string | Yes | Allowed: authorization_code, refresh_token |
| `code` | string | No |  |
| `redirect_uri` | string | No |  |
| `refresh_token` | string | No |  |
| `client_id` | string | No |  |
| `client_secret` | string | No |  |
| `code_verifier` | string | No |  |

Nested schemas and constraints are in the [OpenAPI document](/swivy/openapi.json).

**Responses:** `200` OIDC token response · `400` Invalid grant or token request · `401` Invalid client · `404` Issuer environment not found

## Fetch OIDC userinfo claims [#fetch-oidc-userinfo-claims]

<EndpointHeader method="GET" path="/oidc/{appId}/userinfo" base={false} />

**Auth:** `Authorization: Bearer token (OidcAccessToken)`

| Parameter | Location | Required | Description |
|---|---|---|---|
| `appId` | path | Yes | Environment app identifier |

**Responses:** `200` OIDC userinfo response · `401` Invalid or missing OIDC access token · `404` Issuer environment not found
