API reference
Swivy API reference
Every documented Swivy endpoint, generated from its OpenAPI document.
Preview: not generally available
Swivy runs in staging only and has no public base URL yet. Preview partners receive theirs with their credentials.
Swivy has two kinds of routes:
- Runtime (
/v1/runtime/...,/oidc/...): called by your app for a user. Browsers and phones sendx-swivy-app-id+x-swivy-publishable-key; servers can usex-swivy-secret-key; signed-in calls addAuthorization: Bearer <sessionToken>. - Control plane (
/v1/control/...): server-to-server administration with an organization admin credential inx-swivy-admin-key.
A running Swivy API also serves this contract at /openapi.json and a browsable version at /docs.
| Section | What it covers | Endpoints |
|---|---|---|
| Auth & step-up | Email, wallet and Sign in with Swop login, sessions, passkeys, TOTP and SMS step-up. | 18 |
| Accounts & wallets | Embedded (managed) wallets, linked wallets, custody, export and raw signing. | 9 |
| Intents | Ask Swivy to sign or execute, then read the result. | 3 |
| Session grants | Scoped, expiring wallet access for AI agents and backend jobs. | 5 |
| OIDC (Sign in with Swop) | Discovery, JWKS, authorize, token, userinfo and logout for an issuer environment. | 11 |
| Control plane | Organizations, projects, environments, credentials, policy, RPC targets, webhooks, OIDC clients and audit logs. | 31 |
Errors return JSON with an error code, for example { "error": "mfa_required" }. Some also include reasons (why a request was refused) and supportedActions (what you can do instead).