WebAuthn Registration

Endpoints for WebAuthn credential registration and signup

Generate Registration Options

cURL

curl -X POST https://your-domain.com/recipe/webauthn/options/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "displayName": "John Doe",
    "relyingPartyName": "My App",
    "relyingPartyId": "example.com",
    "origin": "https://example.com",
    "timeout": 60000,
    "attestation": "none",
    "residentKey": "required",
    "userVerification": "preferred",
    "userPresence": false,
    "supportedAlgorithmIDs": [-8, -7, -257]
  }'

200 OK

{
  "status": "OK",
  "webauthnGeneratedOptionsId": "generated-options-id",
  "publicKey": {
    "challenge": "base64-encoded-challenge",
    "rp": {
      "name": "My App",
      "id": "example.com"
    },
    "user": {
      "id": "base64-user-id",
      "name": "[e-mail]",
      "displayName": "John Doe"
    },
    "pubKeyCredParams": [
      {"alg": -8, "type": "public-key"},
      {"alg": -7, "type": "public-key"},
      {"alg": -257, "type": "public-key"}
    ],
    "timeout": 60000,
    "attestation": "none",
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    }
  }
}

email · string · required

User’s email address (will be normalized)

displayName · string

Display name for the user (defaults to email if not provided)

relyingPartyName · string · required

Human-readable name of the relying party (your application)

relyingPartyId · string · required

Relying party identifier (usually your domain)

origin · string · required

Origin URL for credential binding

timeout · number

Timeout in milliseconds (default: 60000)

attestation · string

Attestation conveyance preference: “none”, “indirect”, “direct” (default: “none”)

residentKey · string

Resident key requirement: “required”, “preferred”, “discouraged” (default: “required”)

userVerification · string

User verification requirement: “required”, “preferred”, “discouraged” (default: “preferred”)

userPresence · boolean

Whether user presence is required (default: false)

supportedAlgorithmIDs · array

Array of COSE algorithm identifiers (default: [-8, -7, -257])

status · string

“OK” or “INVALID_OPTIONS_ERROR”

webauthnGeneratedOptionsId · string

Unique identifier for these options (used in subsequent registration call)

publicKey · object

WebAuthn PublicKeyCredentialCreationOptions to pass to navigator.credentials.create()

---

Sign Up with Credential

cURL

curl -X POST https://your-domain.com/recipe/webauthn/signup \
  -H "Content-Type: application/json" \
  -d '{
    "webauthnGeneratedOptionsId": "generated-options-id",
    "credential": {
      "id": "credential-id",
      "rawId": "base64-raw-id",
      "response": {
        "attestationObject": "base64-attestation",
        "clientDataJSON": "base64-client-data"
      },
      "type": "public-key"
    }
  }'

200 OK

{
  "status": "OK",
  "user": {
    "id": "user-id",
    "isPrimaryUser": false,
    "tenantIds": ["public"],
    "emails": ["[e-mail]"],
    "phoneNumbers": [],
    "thirdParty": [],
    "loginMethods": [
      {
        "recipeId": "webauthn",
        "recipeUserId": "recipe-user-id",
        "tenantIds": ["public"],
        "email": "[e-mail]",
        "timeJoined": 1234567890,
        "verified": true,
        "webauthN": {
          "credentialIds": ["credential-id"]
        }
      }
    ],
    "timeJoined": 1234567890
  },
  "webauthnCredentialId": "credential-id",
  "relyingPartyId": "example.com",
  "relyingPartyName": "My App",
  "recipeUserId": "recipe-user-id"
}

webauthnGeneratedOptionsId · string · required

ID from the options generation response

credential · object · required

PublicKeyCredential object from navigator.credentials.create()

status · string

“OK”, “INVALID_OPTIONS_ERROR”, “EMAIL_ALREADY_EXISTS_ERROR”, “INVALID_AUTHENTICATOR_ERROR”, “OPTIONS_NOT_FOUND_ERROR”, or “INVALID_CREDENTIALS_ERROR”

user · object

Created user object with login methods

webauthnCredentialId · string

The credential ID that was registered

recipeUserId · string

The recipe user ID for this WebAuthn login method

---

Register Credential for Existing User

cURL

curl -X POST https://your-domain.com/recipe/webauthn/user/credential/register \
  -H "Content-Type: application/json" \
  -d '{
    "recipeUserId": "recipe-user-id",
    "webauthnGeneratedOptionsId": "generated-options-id",
    "credential": {
      "id": "credential-id",
      "rawId": "base64-raw-id",
      "response": {
        "attestationObject": "base64-attestation",
        "clientDataJSON": "base64-client-data"
      },
      "type": "public-key"
    }
  }'

200 OK

{
  "status": "OK",
  "webauthnCredentialId": "credential-id",
  "recipeUserId": "recipe-user-id",
  "email": "[e-mail]",
  "relyingPartyId": "example.com",
  "relyingPartyName": "My App"
}

recipeUserId · string · required

The recipe user ID to add the credential to

webauthnGeneratedOptionsId · string · required

ID from the options generation response

credential · object · required

PublicKeyCredential object from navigator.credentials.create()

status · string

“OK”, “INVALID_OPTIONS_ERROR”, “INVALID_AUTHENTICATOR_ERROR”, “INVALID_CREDENTIALS_ERROR”, “OPTIONS_NOT_FOUND_ERROR”, “CREDENTIAL_ALREADY_EXISTS_ERROR”, or “UNKNOWN_USER_ID_ERROR”

webauthnCredentialId · string

The credential ID that was registered

recipeUserId · string

The recipe user ID

email · string

User’s email address