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

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

GET/oidc/{appId}/.well-known/openid-configuration

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

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

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

Fetch the issuer JWKS

GET/oidc/{appId}/jwks

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

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

Responses: 200 OIDC JWKS · 404 Issuer environment not found

Request a hosted text-message login code

POST/oidc/{appId}/login/sms/request

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

Request body: required. Hosted SMS login

Content type: application/json.

FieldTypeRequiredDescription
clientIdstringYes
phoneNumberstringYes

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

POST/oidc/{appId}/login/sms/verify

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

Request body: required. Hosted SMS login

Content type: application/json.

FieldTypeRequiredDescription
clientIdstringYes
challengeIdstringYes
codestringYes

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

POST/oidc/{appId}/login/email/request

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

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

Request body: required. Email login payload

Content type: application/json.

FieldTypeRequiredDescription
emailstringYes
externalUserIdstringNo

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

POST/oidc/{appId}/login/email/verify

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

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

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

Request a wallet-login challenge for the hosted OIDC login flow

POST/oidc/{appId}/login/wallet/request

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

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

Verify a wallet-login signature and establish the hosted OIDC session

POST/oidc/{appId}/login/wallet/verify

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

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

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

POST/oidc/{appId}/authorize/consent

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

Request body: required. Hosted consent decision payload

Content type: application/json.

FieldTypeRequiredDescription
client_idstringYes
redirect_uristringYes
scopestringYes
statestringNo
noncestringNo
code_challengestringNo
code_challenge_methodstringNoAllowed: S256
decisionstringYesAllowed: approve, deny
rememberbooleanNo

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

GET/oidc/{appId}/logout

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier
client_idqueryNoOIDC client identifier
post_logout_redirect_uriqueryNoRegistered redirect URI to return the browser to after logout
statequeryNoOpaque 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

GET/oidc/{appId}/authorize

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier
response_typequeryYesOIDC response type
client_idqueryYesOIDC client identifier
redirect_uriqueryYesRegistered redirect URI
scopequeryYesSpace-delimited scopes
statequeryNoOpaque client state value
noncequeryNoNonce echoed into the ID token
code_challengequeryNoPKCE code challenge
code_challenge_methodqueryNoPKCE code challenge method
promptqueryNoOIDC prompt behavior
login_hintqueryNoPrefilled email address for the hosted login screen
screen_hintqueryNoChoose 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

POST/oidc/{appId}/token

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.

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

Request body: required. OIDC token exchange payload

Content type: application/json.

FieldTypeRequiredDescription
grant_typestringYesAllowed: authorization_code, refresh_token
codestringNo
redirect_uristringNo
refresh_tokenstringNo
client_idstringNo
client_secretstringNo
code_verifierstringNo

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

GET/oidc/{appId}/userinfo

Auth: Authorization: Bearer token (OidcAccessToken)

ParameterLocationRequiredDescription
appIdpathYesEnvironment app identifier

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

On this page