Verify a passkey registration and enroll the credential

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program

POST/v1/auth/mfa/passkey/registration/verify

Verifies the browser's registration against the challenge issued to this partial-auth session and stores the credential, active at once. For the account's first second factor the single-use recovery codes are returned exactly ONCE and the flow parks at the recovery-codes step (recovery-ack); for a further factor the session is elevated and redirectTo resumes the flow. A registration that does not verify is answered uniformly (401).

POST/v1/auth/mfa/passkey/registration/verify

curl -X POST 'https://auth.example.com/v1/auth/mfa/passkey/registration/verify' \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "id": "string",
      "rawId": "string",
      "type": "public-key",
      "authenticatorAttachment": "platform",
      "clientExtensionResults": {},
      "response": {
        "clientDataJSON": "string",
        "attestationObject": "string",
        "transports": [
          "string"
        ],
        "authenticatorData": "string",
        "publicKey": "string",
        "publicKeyAlgorithm": 0
      }
    }
  }'

Response

200 OK

{}

Authorization

None. This endpoint does not take API credentials.

It reads the browser session from the Cookie header.

The request Cookie header; the interactive login / pending-auth session cookie, and the browser marker a sign-in is recognized by, are read from it.

Headers

Cookiestring
The request Cookie header; the interactive login / pending-auth session cookie, and the browser marker a sign-in is recognized by, are read from it.
Originstring
Browser Origin, checked (with Sec-Fetch-Site) as a same-origin/CSRF guard.
Sec-Fetch-Sitestring
Fetch metadata; only same-origin is trusted (CSRF guard).
Content-Typestring
Must be application/json — a JSON body cannot be a CORS simple request, closing form-based CSRF.
User-Agentstring
Accept-Languagestring
The browser's preferred languages (RFC 9110 §12.5.4); a message the operation queues, such as a new-sign-in alert, is written in the first one the server ships.

Request body

application/json

The browser's answer to a registration ceremony.

credentialobjectrequired
What PublicKeyCredential.toJSON produces for a created credential.
Show child attributesHide child attributes
- idstringrequired
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
- typeenumrequired
  Possible values1 value
  public-key
- responseobjectrequired
  The authenticator's attestation response (§5.2.1).
  Show child attributesHide child attributes
  clientDataJSONstringrequired
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  attestationObjectstringrequired
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  transportsarray of strings
  at most 8 items · each item: at most 32 characters
  authenticatorDatastring
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  publicKeystring
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  publicKeyAlgorithminteger · int64
- rawIdstring
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
- authenticatorAttachmentenum
  Possible values2 values
  platform
  cross-platform
- clientExtensionResultsobject
labelstring
The user's name for the credential.
at most 64 characters

No other properties are accepted.

Responses

200 OKapplication/jsonThe credential was enrolled.
The credential was enrolled.
Headers
- Set-Cookiearray of strings
- Cache-Controlno-store
Body
A verified registration. When the credential is the account's first second factor the recovery codes are returned once and the flow parks at the recovery-codes step; otherwise the session is elevated and redirectTo resumes the flow.
- codesarray of strings
  The plaintext recovery codes (store securely; not retrievable again).
- redirectTostring
  Where to resume the flow once the session is elevated.
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the last path segment of type), so consumers can branch on it without parsing prose. type is https://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code has about:blank. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"https://nauthera.io/problems/validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values43 values
  invalid_request
  invalid_credentials
  forbidden
  unauthorized
  insufficient_user_authentication
  protected_account
  password_held_by_directory
  last_role_administrator
  invalid_code
  too_many_requests
  too_many_attempts
  account_locked
  account_unavailable
  already_enrolled
  registration_disabled
  registration_conflict
  captcha_failed
  invalid_reset_link
  password_reused
  password_too_short
  password_too_long
  password_compromised
  invalid_verification_link
  invalid_invitation_link
  mail_relay_missing
  email_unverified
  not_found
  conflict
  unavailable
  busy
  window_too_large
  too_many_series
  internal_error
  rate_limited
  malformed
  body_too_large
  required
  validation_error
  unknown_org
  invalid_token
  invalid_dpop_proof
  use_dpop_nonce
  server_error
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457).
Problem details (RFC 9457).
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json). code is a stable machine-readable slug for the problem kind (it mirrors the last path segment of type), so consumers can branch on it without parsing prose. type is https://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code has about:blank. errors is present on validation failures and lists every offending field.
- titlestringrequired
  Example"Request validation failed"
- statusintegerrequired
  Example400
- typestring · uri
  Example"https://nauthera.io/problems/validation_error"
- detailstring
  Example"One or more fields did not satisfy the API schema."
- codeenum
  The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing title or detail, which are English prose for logs. A problem whose status says everything the server knows carries no code.
  Show moreShow less
  validation_error is the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are the errors list — one entry per offending field — which a form renders on those fields. required and malformed are spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.
  
  Compatibility: this is a CLOSED enum, with the same cost as AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.
  Possible values43 values
  invalid_request
  invalid_credentials
  forbidden
  unauthorized
  insufficient_user_authentication
  protected_account
  password_held_by_directory
  last_role_administrator
  invalid_code
  too_many_requests
  too_many_attempts
  account_locked
  account_unavailable
  already_enrolled
  registration_disabled
  registration_conflict
  captcha_failed
  invalid_reset_link
  password_reused
  password_too_short
  password_too_long
  password_compromised
  invalid_verification_link
  invalid_invitation_link
  mail_relay_missing
  email_unverified
  not_found
  conflict
  unavailable
  busy
  window_too_large
  too_many_series
  internal_error
  rate_limited
  malformed
  body_too_large
  required
  validation_error
  unknown_org
  invalid_token
  invalid_dpop_proof
  use_dpop_nonce
  server_error
- instancestring
  Example"/introspect"
- request_idstring
  Example"8d94ed49-1caf-4ab3-9594-557142f2d023"
- trace_idstring
  Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
  Example"4bf92f3577b34da6a3ce929d0e0e4736"
- errorsarray of objects
  Field-level violations (present for validation errors).
  Each item:
  A single field-level validation violation.
  Show item attributesHide item attributes
  fieldstringrequired
  Offending field, dotted for nested bodies (e.g. child.id).
  Example"token_type_hint"
  codestringrequired
  Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
  Example"not_allowed"
  messagestringrequired
  Example"field token_type_hint must be one of [access_token, refresh_token]"

PreviousBegin a passkey registration ceremony NextBegin a passkey authentication ceremony

Authorization

Headers

Request body

Responses

Headers

Body

Body

Body