Begin WebAuthn security key registration
Generates a WebAuthn challenge and registration options to enroll a new hardware security key or passkey for 2-factor authentication. A mailbox bearer or system key acting under its credential must re-prove the current password when an active password credential exists. Account and unacted system administrators, and password-less provisioning, are exempt.
bearerAuthAuthorizationBearer <token>Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.
oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.
oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.
Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].
identityId*stringMailbox identity ULID
application/json- body
currentPassword?stringThe mailbox's current password. Required for a mailbox session (including a relayed session) when an active password exists; omitted for administrators or password-less provisioning
1 <= length <= 1024rpId*stringRelying Party ID (domain hostname)
1 <= length <= 253WebAuthn creation options to pass to navigator.credentials.create()
application/json- response
attestation*"none"Attestation conveyance preference
"none"authenticatorSelection*challenge*stringBase64url-encoded one-time challenge
excludeCredentials*array<>Credentials to exclude to prevent duplicate enrollment
pubKeyCredParams*array<>Supported cryptographic algorithms
rp*timeout*integerCeremony timeout in milliseconds
user*curl -X POST 'https://api.open.email/api/v1/identities/string/webauthn/registrations' \
-H 'Content-Type: application/json' \
-d '{
"rpId": "string"
}'{
"attestation": "none",
"authenticatorSelection": {
"residentKey": "string",
"userVerification": "string"
},
"challenge": "string",
"excludeCredentials": [
{
"id": "string",
"transports": [
"string"
],
"type": "public-key"
}
],
"pubKeyCredParams": [
{
"alg": 0,
"type": "public-key"
}
],
"rp": {
"id": "string",
"name": "string"
},
"timeout": 0,
"user": {
"displayName": "string",
"id": "string",
"name": "string"
}
}Issue mailbox recovery codes POST
Issues a fresh set of ten single-use recovery codes and returns the plaintext exactly once, invalidating any previous set. Requires the current password.
Finish WebAuthn security key registration POST
Verifies the browser WebAuthn attestation response and stores the enrolled security key.