canonical: https://jentic.com/apis/corbado.com/corbado

# Corbado Backend API

Jentic publishes the only available OpenAPI specification for Corbado Backend API, keeping it validated and agent-ready. Corbado provides a passkey-first authentication backend that lets applications register users, issue WebAuthn challenges, manage passkeys and connect tokens, and query auth and passkey events for security analytics. The 45 endpoints cover users, sessions, identifiers, passkeys, SSO, project configuration, webhook endpoints and password manager hints, plus device and client environment tracking. The API uses HTTP Basic authentication where the username is the Corbado project ID and the password is the API secret.

## For AI agents

Manage passkey-based authentication on the Corbado backend, including users, sessions, WebAuthn challenges, identifiers and SSO connections.

## Scope

Does not handle frontend WebAuthn ceremony rendering, MFA SMS delivery, or password storage - use for backend passkey identity management only.

## Capabilities

- Create or update a user record and attach login identifiers like email or username
- Issue a WebAuthn challenge and update its state during a passkey ceremony
- List and revoke passkeys registered to a specific user
- Generate connect tokens that the frontend uses for passkey-mediated transactions
- Read auth events and passkey events for security and conversion analytics
- Configure project-level settings, SSO connections and webhook endpoints

## Use cases

### Passwordless Sign-Up Flow

Consumer apps replacing passwords with passkeys can wire sign-up to Corbado by creating a user and attaching an identifier (email or username), then issuing a passkey registration challenge. POST /users creates the account, POST `/users/{userID}/identifiers` attaches the email, and POST `/users/{userID}/challenges` drives the WebAuthn ceremony.

Example prompt: POST /users with email 'jane@example.com', POST `/users/{userID}/identifiers` attaching the email, then POST `/users/{userID}/challenges` to start passkey registration.

### Step-Up Authentication for Sensitive Actions

Fintech and health apps that need step-up auth before transfers or record changes can use Corbado connect tokens. The backend creates a connect token tied to the user and action, the frontend prompts a passkey ceremony, and a returned challenge result confirms the user authorised the operation before it executes.

Example prompt: Create a connect token for user 'usr_123' tied to 'wire-transfer-9999' and return the token to the frontend for the WebAuthn step-up flow.

### Auth Analytics and Suspicious-Login Triage

Security teams can query Corbado's auth events and passkey events to investigate suspicious sign-ins, list per-user passkeys, and revoke compromised credentials. Combined with the device tracking endpoints this gives a per-user authentication footprint for triage.

Example prompt: List passkey events for user 'usr_456' over the last 30 days, then DELETE the passkey ID flagged as registered from an unfamiliar device.

### AI Agent Identity Operations

An admin-side AI agent can answer support tickets like 'remove the lost passkey from my account' by calling Corbado through Jentic. The agent searches by intent, loads the schema for passkey deletion, and executes against the matching path while Jentic keeps the project-id and API secret in the credential vault.

Example prompt: Use Jentic to list passkeys for the user, identify the one matching the device the user reported lost, and DELETE it.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/users` | Create a new user |
| GET | `/users` | List users |
| GET | `/users/{userID}` | Retrieve a user |
| PATCH | `/users/{userID}` | Update a user |
| POST | `/users/{userID}/challenges` | Create a passkey challenge for a user |
| POST | `/users/{userID}/identifiers` | Attach a login identifier to a user |
| DELETE | `/users/{userID}` | Delete a user |

## Key resources

- **Users** — User CRUD with identifier and challenge sub-resources
- **Sessions** — Session tokens issued to authenticated users
- **Challenges** — WebAuthn challenges including registration and login ceremonies
- **Identifiers** — Login identifiers (email, username, phone) attached to users
- **Passkeys** — Registered passkeys with revocation
- **SSO** — Single sign-on connection management
- **AuthEvents** — Authentication audit events
- **PasskeyEvents** — Passkey lifecycle audit events
- **ProjectConfig** — Project-level configuration
- **ConnectTokens** — Step-up tokens for transaction authorisation
- **WebhookEndpoints** — Webhook subscriptions for auth and passkey events
- **PasswordManagers** — Hints for the calling client about saved credentials
- **ClientEnvs** — Frontend environment configuration
- **Devices** — Devices a user has authenticated from

## Why Jentic

- **Setup:** Wiring Corbado by hand means combining the project id and API secret into a Basic auth header and coding the passkey user, challenge, and identifier calls yourself. Through Jentic you install once, import the Corbado Backend API from the API Directory, store both values once, and your agent calls it.
- **Permission scoping:** Corbado's user operations carry the target user id in the request, so scope this by operations: allow the agent the calls it needs, such as creating users and issuing challenges, and leave user deletion out unless you add it. Each operation you credit the agent with stays inside that allowed set.
- **Credential handling:** Your Corbado project id and API secret are stored once, encrypted, by your own Jentic One instance and used to build the Basic auth header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Corbado user' or 'issue a passkey challenge', and Jentic returns the matching operation with its request body schema, mapping the passkey, challenge, and identifier sub-resources so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0 API** — Broader identity platform with passwords, social login and passkeys
- **Okta API** — Enterprise identity provider with passkey support and workforce-grade SSO
- **Stytch API** — Developer-first auth provider with passkeys, magic links and SMS OTP

## FAQ

### Why is there no official OpenAPI spec for Corbado Backend API?

Corbado does not publish an OpenAPI specification at this URL. Jentic generates and maintains this spec so that AI agents and developers can call Corbado Backend API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Corbado Backend API use?

The backend API uses HTTP Basic authentication. The username is the Corbado project ID and the password is the API secret. Jentic stores the project ID and secret in the credential vault and constructs the Basic header at execution time.

### Can I register a passkey for a new user with the Corbado Backend API?

Yes. Create the user with POST /users, attach an identifier with POST `/users/{userID}/identifiers`, then drive the WebAuthn registration ceremony with POST `/users/{userID}/challenges` and PATCH `/users/{userID}/challenges/{challengeID}` to update the challenge state.

### How do I revoke a passkey on the Corbado Backend API?

DELETE the passkey resource for the user (under the Passkeys tag in the spec). For audit context, list PasskeyEvents for the same user first to confirm which credential was used from the suspicious device before revoking.

### What rate limits apply to the Corbado Backend API?

The OpenAPI spec does not declare formal rate limits. Treat WebAuthn challenge endpoints as user-driven (one per ceremony) and back off on HTTP 429 with exponential delay during bulk operations.

### How do I create a Corbado user through Jentic with the Corbado Backend API?

Run pip install jentic, search Jentic with 'create Corbado user', load the operation schema for POST /users and execute it with the user's email or username; the project ID and API secret are injected by Jentic from the vault.

### Can I limit what my agent is allowed to do with the Corbado Backend API?

Yes. Because you run Jentic One yourself, your own rules decide which Corbado operations the agent may call and which credentials it may use. Corbado's user operations carry the target user ID in the request, so you scope access per operation: grant the agent only the calls it needs, such as creating users with POST /users and issuing WebAuthn challenges with POST `/users/{userID}/challenges`, and leave destructive calls like DELETE `/users/{userID}` out of the allowed set. Each operation the agent is credited with stays inside that boundary, and the project ID and API secret are supplied at execution time rather than exposed to the agent.