OIDC & MCP
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.
13 operations from the November 1, 2026 deployed contract. Full OpenAPI schema · Live interactive reference.
Fetch the OIDC discovery document
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
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
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.
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
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.
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
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.
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
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.
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
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.
Responses: 200 Wallet login challenge · 404 Issuer environment not found
Verify a wallet-login signature and establish the hosted OIDC session
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.
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
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.
Responses: 200 Consent decision redirect target · 400 Invalid consent request · 401 Login required · 404 Issuer environment not found
End the hosted OIDC session
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
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
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.
Responses: 200 OIDC token response · 400 Invalid grant or token request · 401 Invalid client · 404 Issuer environment not found
Fetch OIDC userinfo claims
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