Skip to main content
POST/gate/passkeys/register/begin

Begin Passkey Registration

Initiates WebAuthn passkey registration for the authenticated end-user by returning a credential creation challenge.

The challenge is used by the client-side WebAuthn API to prompt the user's authenticator (platform authenticators such as Touch ID or Windows Hello, or cross-platform keys such as a YubiKey); the resulting attestation is submitted to the finish endpoint to complete enrollment.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
401K9O_SESSION_EXPIREDThe session used to initiate passkey registration has expired; sign in again.
401K9O_MFA_REQUIREDAn MFA challenge must be completed before passkey registration can begin.
404K9O_END_USER_NOT_FOUNDThe authenticated end-user record could not be found in this project.
Response body (200)
data *object

WebAuthn registration options (PublicKeyCredentialCreationOptionsJSON).

Pass them to the browser, for example to startRegistration() from @simplewebauthn/browser, then send the result to register/finish.

challenge *string

A random challenge, base64url.

It is held for this ceremony and works once; pass the options to the browser unchanged.

rp *object

The relying party (the site) the passkey is for.

name *string

The relying party name the browser shows, set by the deployment.

id *string

The relying party id: the domain the passkey is bound to, set by the deployment.

user *object

The account the passkey is created for.

id *string

The end user's id as WebAuthn user handle: the UTF-8 bytes of the eu_... id, base64url.

name *string

The end user's id (eu_...).

displayName *string

Always empty.

pubKeyCredParams *object[]

The signature algorithms accepted, most preferred first: EdDSA (-8), ES256 (-7) and RS256 (-257).

alg *integer

A COSE algorithm id.

type *"public-key"

The credential type.

Always public-key.

timeout *integer

How long the browser may wait for the end user, in milliseconds.

Always 60000.

attestation *"none"

No attestation is requested.

excludeCredentials *object[]

The end user's passkeys already registered, so the authenticator does not register the same one twice.

Empty when there are none.

id *string

The credential id, base64url.

transports *string[]

How the browser can reach the authenticator, as the authenticator reported at registration (usb, nfc, ble, internal, hybrid, ...).

type *"public-key"

The credential type.

Always public-key.

authenticatorSelection *object

What kind of authenticator to use.

residentKey *"preferred"

A discoverable credential is preferred.

userVerification *"preferred"

User verification (biometric or PIN) is preferred.

requireResidentKey *boolean

Always false.

extensions *object

WebAuthn extensions requested.

credProps *true

Asks the browser to report whether the credential is discoverable.

meta *any

Request metadata: cost, timing and the request and trace ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.gate.passkeys.register.begin()

Showing example in TypeScript

Response example (200)
{
  "data": {
    "challenge": "string",
    "rp": {
      "name": "string",
      "id": "string"
    },
    "user": {
      "id": "string",
      "name": "string",
      "displayName": "string"
    },
    "pubKeyCredParams": [
      {
        "alg": 0,
        "type": "public-key"
      }
    ],
    "timeout": 0,
    "attestation": "none",
    "excludeCredentials": [
      {
        "id": "string",
        "transports": [
          "string"
        ],
        "type": "public-key"
      }
    ],
    "authenticatorSelection": {
      "residentKey": "preferred",
      "userVerification": "preferred",
      "requireResidentKey": false
    },
    "extensions": {
      "credProps": true
    }
  }
}

More in Sign-in & Sessions