Create, list, retrieve, update, and delete end users, plus manage their social logins and credentials, in the Corbado Backend API.
openapi: 3.0.1
info:
title: Corbado Backend API
description: >-
The Corbado Backend API is a server-to-server REST API for the Corbado
passkey-first authentication platform. It manages users, login identifiers,
sessions, passkeys (WebAuthn credentials), passkey events, Connect tokens,
and project data exports. Requests authenticate with HTTP Basic auth using
the project ID as username and the API secret as password (both obtained
from the Corbado Developer Panel).
termsOfService: https://www.corbado.com/legal/terms
contact:
name: Corbado Support
url: https://docs.corbado.com
email: support@corbado.com
version: 2.0.0
servers:
- url: https://backendapi.corbado.io/v2
description: Corbado Backend API v2
security:
- basicAuth: []
tags:
- name: Users
description: Create and manage end users and their social logins and credentials.
- name: Identifiers
description: Manage login identifiers (email, phone, username) attached to a user.
- name: Sessions
description: List and revoke authenticated sessions.
- name: Passkeys
description: WebAuthn passkey registration and login ceremonies and verification.
- name: PasskeyEvents
description: Record and query passkey lifecycle events for a user.
- name: ConnectTokens
description: Short-lived tokens authorizing Corbado Connect frontend flows.
- name: Exports
description: Project data exports and download links.
paths:
/users:
post:
operationId: userCreate
tags:
- Users
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreateReq'
responses:
'200':
description: The created user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/ErrorRsp'
'401':
$ref: '#/components/responses/ErrorRsp'
get:
operationId: userList
tags:
- Users
summary: List users
parameters:
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: A paged list of users.
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'401':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}:
parameters:
- $ref: '#/components/parameters/UserID'
get:
operationId: userGet
tags:
- Users
summary: Retrieve a user
responses:
'200':
description: The requested user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/ErrorRsp'
patch:
operationId: userUpdate
tags:
- Users
summary: Update a user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdateReq'
responses:
'200':
description: The updated user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/ErrorRsp'
delete:
operationId: userDelete
tags:
- Users
summary: Delete a user
responses:
'200':
description: The user was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericRsp'
'404':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}/credentials:
parameters:
- $ref: '#/components/parameters/UserID'
get:
operationId: userCredentialList
tags:
- Users
summary: List passkeys for user
responses:
'200':
description: The user's passkey credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialList'
'404':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}/credentials/{credentialID}:
parameters:
- $ref: '#/components/parameters/UserID'
- name: credentialID
in: path
required: true
schema:
type: string
delete:
operationId: userCredentialDelete
tags:
- Users
summary: Delete passkey
responses:
'200':
description: The passkey credential was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericRsp'
'404':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}/identifiers:
parameters:
- $ref: '#/components/parameters/UserID'
post:
operationId: identifierCreate
tags:
- Identifiers
summary: Create login identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentifierCreateReq'
responses:
'200':
description: The created login identifier.
content:
application/json:
schema:
$ref: '#/components/schemas/Identifier'
'400':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}/identifiers/{identifierID}:
parameters:
- $ref: '#/components/parameters/UserID'
- name: identifierID
in: path
required: true
schema:
type: string
patch:
operationId: identifierUpdate
tags:
- Identifiers
summary: Update identifier
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentifierUpdateReq'
responses:
'200':
description: The updated identifier.
content:
application/json:
schema:
$ref: '#/components/schemas/Identifier'
'404':
$ref: '#/components/responses/ErrorRsp'
delete:
operationId: identifierDelete
tags:
- Identifiers
summary: Delete identifier
responses:
'200':
description: The identifier was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericRsp'
'404':
$ref: '#/components/responses/ErrorRsp'
/identifiers:
get:
operationId: identifierList
tags:
- Identifiers
summary: List all login identifiers
parameters:
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: A paged list of login identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/IdentifierList'
'401':
$ref: '#/components/responses/ErrorRsp'
/sessions:
get:
operationId: sessionList
tags:
- Sessions
summary: List all sessions
parameters:
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: A paged list of sessions.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionList'
'401':
$ref: '#/components/responses/ErrorRsp'
/sessions/{sessionID}/revoke:
parameters:
- name: sessionID
in: path
required: true
schema:
type: string
post:
operationId: sessionRevoke
tags:
- Sessions
summary: Revoke a session
responses:
'200':
description: The session was revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericRsp'
'404':
$ref: '#/components/responses/ErrorRsp'
/passkey/append/start:
post:
operationId: passkeyAppendStart
tags:
- Passkeys
summary: Start creating passkey
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyAppendStartReq'
responses:
'200':
description: WebAuthn credential creation options.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyStartRsp'
'400':
$ref: '#/components/responses/ErrorRsp'
/passkey/append/finish:
post:
operationId: passkeyAppendFinish
tags:
- Passkeys
summary: Finish creating passkey
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyFinishReq'
responses:
'200':
description: The newly registered passkey.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyData'
'400':
$ref: '#/components/responses/ErrorRsp'
/passkey/login/start:
post:
operationId: passkeyLoginStart
tags:
- Passkeys
summary: Start passkey login
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyLoginStartReq'
responses:
'200':
description: WebAuthn credential request options.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyStartRsp'
'400':
$ref: '#/components/responses/ErrorRsp'
/passkey/login/finish:
post:
operationId: passkeyLoginFinish
tags:
- Passkeys
summary: Finish passkey login
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyFinishReq'
responses:
'200':
description: The authenticated passkey and user.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyLoginFinishRsp'
'400':
$ref: '#/components/responses/ErrorRsp'
/passkey/mediation/start:
post:
operationId: passkeyMediationStart
tags:
- Passkeys
summary: Start passkey login (Conditional UI)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyLoginStartReq'
responses:
'200':
description: WebAuthn credential request options for conditional UI.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyStartRsp'
'400':
$ref: '#/components/responses/ErrorRsp'
/passkey/mediation/finish:
post:
operationId: passkeyMediationFinish
tags:
- Passkeys
summary: Finish passkey login (Conditional UI)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyFinishReq'
responses:
'200':
description: The authenticated passkey and user.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyLoginFinishRsp'
'400':
$ref: '#/components/responses/ErrorRsp'
/passkey/verifySignedData:
post:
operationId: passkeyVerifySignedData
tags:
- Passkeys
summary: Verify signed passkey data
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyVerifySignedDataReq'
responses:
'200':
description: The verification result.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyVerifySignedDataRsp'
'400':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}/passkeyEvents:
parameters:
- $ref: '#/components/parameters/UserID'
post:
operationId: passkeyEventCreate
tags:
- PasskeyEvents
summary: Create passkey event
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyEventCreateReq'
responses:
'200':
description: The created passkey event.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyEvent'
'400':
$ref: '#/components/responses/ErrorRsp'
get:
operationId: passkeyEventList
tags:
- PasskeyEvents
summary: List passkey events
responses:
'200':
description: A list of passkey events for the user.
content:
application/json:
schema:
$ref: '#/components/schemas/PasskeyEventList'
'404':
$ref: '#/components/responses/ErrorRsp'
/users/{userID}/passkeyEvents/{passkeyEventID}:
parameters:
- $ref: '#/components/parameters/UserID'
- name: passkeyEventID
in: path
required: true
schema:
type: string
delete:
operationId: passkeyEventDelete
tags:
- PasskeyEvents
summary: Delete passkey event
responses:
'200':
description: The passkey event was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericRsp'
'404':
$ref: '#/components/responses/ErrorRsp'
/connectTokens:
post:
operationId: connectTokenCreate
tags:
- ConnectTokens
summary: Create ConnectToken
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectTokenCreateReq'
responses:
'200':
description: The created Connect token, including its secret.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectToken'
'400':
$ref: '#/components/responses/ErrorRsp'
get:
operationId: connectTokenList
tags:
- ConnectTokens
summary: List ConnectTokens
parameters:
- $ref: '#/components/parameters/Sort'
- $ref: '#/components/parameters/Filter'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: A paged list of Connect tokens.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectTokenList'
'401':
$ref: '#/components/responses/ErrorRsp'
/connectTokens/{connectTokenID}:
parameters:
- name: connectTokenID
in: path
required: true
schema:
type: string
patch:
operationId: connectTokenUpdate
tags:
- ConnectTokens
summary: Update ConnectToken
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectTokenUpdateReq'
responses:
'200':
description: The updated Connect token.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectToken'
'404':
$ref: '#/components/responses/ErrorRsp'
delete:
operationId: connectTokenDelete
tags:
- ConnectTokens
summary: Delete ConnectToken
responses:
'200':
description: The Connect token was deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericRsp'
'404':
$ref: '#/components/responses/ErrorRsp'
/exports/{exportType}:
parameters:
- name: exportType
in: path
required: true
schema:
type: string
enum:
- users
- passkeyEvents
get:
operationId: exportList
tags:
- Exports
summary: List project exports
responses:
'200':
description: A list of available export files.
content:
application/json:
schema:
$ref: '#/components/schemas/ExportList'
'404':
$ref: '#/components/responses/ErrorRsp'
/exports/{exportType}/{filename}/downloadLink:
parameters:
- name: exportType
in: path
required: true
schema:
type: string
- name: filename
in: path
required: true
schema:
type: string
get:
operationId: exportDownloadLink
tags:
- Exports
summary: Get export download link
responses:
'200':
description: A time-limited download link for the export file.
content:
application/json:
schema:
$ref: '#/components/schemas/ExportDownloadLink'
'404':
$ref: '#/components/responses/ErrorRsp'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. The username is the project ID
(e.g. pro-1234567890) and the password is the API secret, both
issued from the Corbado Developer Panel.
parameters:
UserID:
name: userID
in: path
required: true
description: The Corbado user ID (e.g. usr-4693224802260150919).
schema:
type: string
Sort:
name: sort
in: query
required: false
description: Field and direction to sort by, e.g. created:desc.
schema:
type: string
Filter:
name: filter
in: query
required: false
description: Repeatable filter expressions, e.g. status:eq:active.
schema:
type: array
items:
type: string
Page:
name: page
in: query
required: false
schema:
type: integer
format: int32
default: 1
PageSize:
name: pageSize
in: query
required: false
schema:
type: integer
format: int32
default: 10
responses:
ErrorRsp:
description: An error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorRsp'
schemas:
User:
type: object
required:
- userID
- status
- updated
- updatedMs
properties:
userID:
type: string
example: usr-4693224802260150919
status:
type: string
enum:
- pending
- active
- disabled
fullName:
type: string
example: Jane Doe
explicitWebauthnID:
type: string
updated:
type: string
format: date-time
updatedMs:
type: integer
format: int64
UserCreateReq:
type: object
required:
- status
properties:
status:
type: string
enum:
- pending
- active
- disabled
fullName:
type: string
explicitWebauthnID:
type: string
UserUpdateReq:
type: object
properties:
status:
type: string
enum:
- pending
- active
- disabled
fullName:
type: string
UserList:
type: object
required:
- users
- paging
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
paging:
$ref: '#/components/schemas/Paging'
Identifier:
type: object
required:
- identifierID
- userID
- identifierType
- identifierValue
- status
properties:
identifierID:
type: string
example: emai-2398470283402934
userID:
type: string
identifierType:
type: string
enum:
- email
- phone
- username
identifierValue:
type: string
example: jane.doe@example.com
status:
type: string
enum:
- primary
- verified
- pending
created:
type: string
format: date-time
IdentifierCreateReq:
type: object
required:
- identifierType
- identifierValue
- status
properties:
identifierType:
type: string
enum:
- email
- phone
- username
identifierValue:
type: string
status:
type: string
enum:
- primary
- verified
- pending
IdentifierUpdateReq:
type: object
properties:
status:
type: string
enum:
- primary
- verified
- pending
IdentifierList:
type: object
required:
- identifiers
- paging
properties:
identifiers:
type: array
items:
$ref: '#/components/schemas/Identifier'
paging:
$ref: '#/components/schemas/Paging'
Session:
type: object
required:
- sessionID
- userID
properties:
sessionID:
type: string
userID:
type: string
expiresMs:
type: integer
format: int64
created:
type: string
format: date-time
SessionList:
type: object
required:
- sessions
- paging
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/Session'
paging:
$ref: '#/components/schemas/Paging'
PasskeyData:
type: object
properties:
credentialID:
type: string
userID:
type: string
attestationType:
type: string
transports:
type: array
items:
type: string
backupEligible:
type: boolean
backupState:
type: boolean
aaguid:
type: string
created:
type: string
format: date-time
CredentialList:
type: object
required:
- credentials
properties:
credentials:
type: array
items:
$ref: '#/components/schemas/PasskeyData'
PasskeyAppendStartReq:
type: object
required:
- userID
properties:
userID:
type: string
clientInformation:
$ref: '#/components/schemas/ClientInformation'
PasskeyLoginStartReq:
type: object
properties:
identifierValue:
type: string
clientInformation:
$ref: '#/components/schemas/ClientInformation'
PasskeyFinishReq:
type: object
required:
- signedChallenge
properties:
signedChallenge:
type: string
description: The serialized WebAuthn attestation or assertion response from the browser.
clientInformation:
$ref: '#/components/schemas/ClientInformation'
PasskeyStartRsp:
type: object
properties:
challenge:
type: string
description: The serialized PublicKeyCredentialCreationOptions or PublicKeyCredentialRequestOptions JSON.
PasskeyLoginFinishRsp:
type: object
properties:
userID:
type: string
passkey:
$ref: '#/components/schemas/PasskeyData'
PasskeyVerifySignedDataReq:
type: object
required:
- signedData
properties:
userID:
type: string
signedData:
type: string
PasskeyVerifySignedDataRsp:
type: object
properties:
valid:
type: boolean
userID:
type: string
PasskeyEvent:
type: object
required:
- passkeyEventID
- userID
- passkeyEventType
properties:
passkeyEventID:
type: string
userID:
type: string
passkeyEventType:
type: string
enum:
- login-success
- login-error
- registration-success
- registration-error
- login-error-untrusted
created:
type: string
format: date-time
PasskeyEventCreateReq:
type: object
required:
- passkeyEventType
properties:
passkeyEventType:
type: string
enum:
- login-success
- login-error
- registration-success
- registration-error
- login-error-untrusted
clientInformation:
$ref: '#/components/schemas/ClientInformation'
PasskeyEventList:
type: object
required:
- passkeyEvents
properties:
passkeyEvents:
type: array
items:
$ref: '#/components/schemas/PasskeyEvent'
ConnectToken:
type: object
required:
- connectTokenID
- connectTokenType
properties:
connectTokenID:
type: string
connectTokenType:
type: string
enum:
- passkey-append
- passkey-delete
- passkey-list
secret:
type: string
description: The token secret returned only on creation, passed to the Corbado Connect frontend component.
identifierValue:
type: string
status:
type: string
created:
type: string
format: date-time
ConnectTokenCreateReq:
type: object
required:
- connectTokenType
properties:
connectTokenType:
type: string
enum:
- passkey-append
- passkey-delete
- passkey-list
identifierValue:
type: string
data:
type: string
description: Opaque application-specific data carried with the token.
ConnectTokenUpdateReq:
type: object
properties:
status:
type: string
ConnectTokenList:
type: object
required:
- connectTokens
- paging
properties:
connectTokens:
type: array
items:
$ref: '#/components/schemas/ConnectToken'
paging:
$ref: '#/components/schemas/Paging'
ExportList:
type: object
required:
- exports
properties:
exports:
type: array
items:
type: object
properties:
filename:
type: string
sizeBytes:
type: integer
format: int64
created:
type: string
format: date-time
ExportDownloadLink:
type: object
properties:
url:
type: string
format: uri
expiresMs:
type: integer
format: int64
ClientInformation:
type: object
description: Client/browser context captured for passkey intelligence and risk analysis.
properties:
bluetoothAvailable:
type: boolean
userAgent:
type: string
clientEnvHandle:
type: string
javaScriptHighEntropy:
type: string
Paging:
type: object
properties:
page:
type: integer
format: int32
totalPages:
type: integer
format: int32
totalItems:
type: integer
format: int32
GenericRsp:
type: object
properties:
httpStatusCode:
type: integer
format: int32
message:
type: string
requestData:
$ref: '#/components/schemas/RequestData'
runtime:
type: number
format: float
ErrorRsp:
type: object
required:
- httpStatusCode
- message
properties:
httpStatusCode:
type: integer
format: int32
message:
type: string
requestData:
$ref: '#/components/schemas/RequestData'
runtime:
type: number
format: float
error:
type: object
properties:
type:
type: string
details:
type: string
validation:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
RequestData:
type: object
properties:
requestID:
type: string
link:
type: string