Verify a passkey assertion during sign-in (step-up)

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

POST/v1/auth/mfa/passkey/authentication/verify

Verifies the browser's assertion against the challenge issued to this partial-auth session and the credential's stored key. On success the session is elevated and redirectTo resumes the flow. Failures are uniform (401).

POST/v1/auth/mfa/passkey/authentication/verify

curl -X POST 'https://auth.example.com/v1/auth/mfa/passkey/authentication/verify' \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "id": "string",
      "rawId": "string",
      "type": "public-key",
      "authenticatorAttachment": "platform",
      "clientExtensionResults": {},
      "response": {
        "clientDataJSON": "string",
        "authenticatorData": "string",
        "signature": "string",
        "userHandle": "string"
      }
    }
  }'

Response

200 OK

{
  "redirectTo": "/authorize?client_id=nauthera_2Rk9&response_type=code&..."
}

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 an authentication ceremony.

credentialobjectrequired
What PublicKeyCredential.toJSON produces for an assertion.
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 assertion response (§5.2.2).
  Show child attributesHide child attributes
  clientDataJSONstringrequired
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  authenticatorDatastringrequired
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  signaturestringrequired
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
  userHandlestring
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
- rawIdstring
  Bytes, base64url-encoded without padding.
  at most 8192 characters · pattern ^[A-Za-z0-9_-]*$
- authenticatorAttachmentenum
  Possible values2 values
  platform
  cross-platform
- clientExtensionResultsobject

No other properties are accepted.

Responses

200 OKapplication/jsonThe assertion was accepted; the session is elevated.
The assertion was accepted; the session is elevated.
Headers
- Set-Cookiearray of strings
- Cache-Controlno-store
Body
The next step for the hosted UI after an auth action. redirectTo (when present) is a server-built URL the browser follows — the /authorize continuation or the final client redirect. The MFA/consent fields are reserved for the interactive flows layered on top of this step.
- redirectTostring
  URL to navigate to next (the /authorize continuation or client redirect).
  Example"/authorize?client_id=nauthera_2Rk9&response_type=code&..."
- mfaRequiredboolean
  An MFA challenge is required before completing sign-in.
- mfaMethodsarray of strings
  Available MFA methods, most-preferred first: on a challenge the one the user answered with last leads, and the user may choose any other.
- consentRequiredboolean
  User consent is required before issuing tokens.
- setupRequiredboolean
  The user has no active second factor the policy permits and must enroll one of mfaMethods before sign-in can complete.
- emailVerificationRequiredboolean
  The organization requires a verified address and this account's is not. No session was established; a verification link was sent if one could be, and POST /v1/auth/verify-email/resend sends another.
- passkeyOfferedboolean
  The password verified and the account holds no passkey where passwordless sign-in is open: no session yet, and the user is offered to add one through the passkey registration ceremony, or declines through POST /v1/auth/mfa/passkey/offer/decline, either of which completes the sign-in.
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 authentication ceremony NextDecline the offer to add a passkey and complete the sign-in

Authorization

Headers

Request body

Responses

Headers

Body

Body

Body