Auth & step-up
Email, wallet and Sign in with Swop login, sessions, passkeys, TOTP and SMS step-up.
Preview: not generally available
Swivy runs in staging only. Paths and fields can change before general availability. There is no public base URL yet; preview partners get theirs with their credentials.
Runtime routes your app calls on behalf of a user. Login routes take your x-swivy-app-id and x-swivy-publishable-key; once a user is signed in, send their session as Authorization: Bearer <sessionToken>.
18 endpoints, generated from Swivy's OpenAPI document (apps/api/src/openapi.ts).
Request an email login code
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key (server only)
Request body: Email login payload
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
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key (server only)
Request body: Email verification payload
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
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 (server only)
Request body: OIDC token exchange payload
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
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 (server only)
Request body: Wallet login request payload
Responses: 200 Wallet login challenge · 401 Missing or invalid environment credentials
Verify a wallet-login signature and create a runtime session
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 (server only)
Request body: Wallet login verification payload
Responses: 200 Runtime session and profile · 401 Invalid wallet signature or environment credentials
Get public runtime auth and signup configuration for the current environment
Auth: x-swivy-app-id + x-swivy-publishable-key or x-swivy-app-id + x-swivy-secret-key (server only)
Responses: 200 Runtime auth configuration · 401 Missing or invalid environment credentials
Get the current runtime profile
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Responses: 200 Runtime profile · 401 Invalid runtime session or environment credentials
Claim or update the current runtime user's Swivy username
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Username claim payload
Responses: 200 Username claimed · 400 Invalid or reserved username · 401 Invalid runtime session or environment credentials · 409 Username already taken
Look up a Swivy username in the current project
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Parameters
Responses: 200 Swivy username lookup · 401 Invalid runtime session or environment credentials · 404 Username not found
Start TOTP enrollment
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: TOTP enrollment payload
Responses: 200 TOTP enrollment created · 401 Invalid runtime session or environment credentials
Verify a TOTP enrollment code
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: TOTP verification payload
Responses: 200 TOTP verified · 401 Invalid TOTP code or runtime session · 404 Auth method not found
Start passkey registration
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Passkey registration payload
Responses: 200 Passkey registration challenge and options · 401 Invalid runtime session or environment credentials · 404 Identity not found
Finish passkey registration
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Passkey registration verification payload
Responses: 200 Passkey registration completed · 401 Invalid passkey registration · 404 Challenge or auth method not found · 409 Passkey already registered
Import a passkey public key directly
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Direct passkey import payload
Responses: 200 Passkey created · 401 Invalid runtime session or environment credentials
Start SMS MFA enrollment
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: SMS enrollment payload
Responses: 200 SMS enrollment created · 401 Invalid runtime session or environment credentials · 502 SMS delivery failed
Verify an SMS enrollment code
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: SMS verification payload
Responses: 200 SMS verified · 401 Invalid SMS code or runtime session · 404 Challenge or auth method not found
Create a step-up challenge
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: MFA challenge payload
Responses: 200 Challenge created · 400 Challenge could not be created · 401 Invalid runtime session or environment credentials · 404 Active auth method not found · 502 SMS delivery failed
Verify a step-up challenge
Auth: x-swivy-app-id + x-swivy-publishable-key + Authorization: Bearer <sessionToken> or x-swivy-app-id + x-swivy-secret-key (server only) + Authorization: Bearer <sessionToken>
Request body: Challenge verification payload
Responses: 200 Challenge verified · 400 Missing passkey assertion · 401 Invalid verification code or signature · 404 Challenge or auth method not found