Sign in with a passkey and no password

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

POST/v1/auth/passkey/verify

Like a password sign-in, it must name a client_id registered in the organization or the device verification page as continue_path, or it is refused with 404 not_found before the assertion is checked.

Verifies the browser's assertion: the credential is resolved within the organization by its own identifier, the user handle it reports must name the account the credential was issued for, and the signature must verify under the stored key. The sign-in is admitted only where the resolved second-factor policy of the deployment, the organization and the client opens passwordless sign-in. A credential that verified its user establishes a session on its own (acr aal2); one that did not continues to the second-factor step the policy and the account's other factors call for, exactly as a verified password does. Every refusal — an unknown credential, a foreign or absent handle, a bad signature, a closed policy — is the one 401 invalid_credentials.

POST/v1/auth/passkey/verify

curl -X POST 'https://auth.example.com/v1/auth/passkey/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

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.
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.

Request body

application/json

A passwordless sign-in: the browser's assertion for a discoverable credential, and the preserved OAuth authorization parameters the server re-validates against the client registry, the same set SignInRequest carries.

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
client_idstring
at most 256 characters
ui_localesstring
at most 256 characters
redirect_uristring
at most 2048 characters
response_typestring
at most 32 characters
scopestring
at most 2048 characters
statestring
at most 1024 characters
noncestring
at most 1024 characters
code_challengestring
at most 128 characters
code_challenge_methodstring
at most 16 characters
login_hintstring
at most 512 characters
promptstring
at most 64 characters
request_uristring
at most 512 characters
resourcestring
at most 2048 characters
authorization_detailsstring
at most 8192 characters
dpop_jktstring
exactly 43 characters · pattern ^[A-Za-z0-9_-]+$
max_ageinteger · int64
at least 0
continue_pathstring
at most 128 characters

No other properties are accepted.

Responses

200 OKapplication/jsonAuthentication succeeded (a session was established) or a next step is required.
Authentication succeeded (a session was established) or a next step is required.
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 passwordless passkey sign-in NextRedeem a single-use recovery code during sign-in

Authorization

Headers

Request body

Responses

Headers

Body

Body

Body