# Begin Passkey Registration

`POST /gate/passkeys/register/begin` · Identity & Access · Sign-in & Sessions

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

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | WebAuthn registration options (`PublicKeyCredentialCreationOptionsJSON`). Pass them to the browser, for example to `startRegistration()` from `@simplewebauthn/browser`, then send the result to register/finish. |
| `data.challenge` | string | yes | A random challenge, base64url. It is held for this ceremony and works once; pass the options to the browser unchanged. |
| `data.rp` | object | yes | The relying party (the site) the passkey is for. |
| `data.rp.name` | string | yes | The relying party name the browser shows, set by the deployment. |
| `data.rp.id` | string | yes | The relying party id: the domain the passkey is bound to, set by the deployment. |
| `data.user` | object | yes | The account the passkey is created for. |
| `data.user.id` | string | yes | The end user's id as WebAuthn user handle: the UTF-8 bytes of the `eu_...` id, base64url. |
| `data.user.name` | string | yes | The end user's id (`eu_...`). |
| `data.user.displayName` | string | yes | Always empty. |
| `data.pubKeyCredParams` | array of object | yes | The signature algorithms accepted, most preferred first: EdDSA (-8), ES256 (-7) and RS256 (-257). |
| `data.pubKeyCredParams.[]alg` | integer | yes | A COSE algorithm id. |
| `data.pubKeyCredParams.[]type` | enum ("public-key") | yes | The credential type. Always `public-key`. |
| `data.timeout` | integer | yes | How long the browser may wait for the end user, in milliseconds. Always 60000. |
| `data.attestation` | enum ("none") | yes | No attestation is requested. |
| `data.excludeCredentials` | array of object | yes | The end user's passkeys already registered, so the authenticator does not register the same one twice. Empty when there are none. |
| `data.excludeCredentials.[]id` | string | yes | The credential id, base64url. |
| `data.excludeCredentials.[]transports` | array of string | yes | How the browser can reach the authenticator, as the authenticator reported at registration (`usb`, `nfc`, `ble`, `internal`, `hybrid`, ...). |
| `data.excludeCredentials.[]type` | enum ("public-key") | yes | The credential type. Always `public-key`. |
| `data.authenticatorSelection` | object | yes | What kind of authenticator to use. |
| `data.authenticatorSelection.residentKey` | enum ("preferred") | yes | A discoverable credential is preferred. |
| `data.authenticatorSelection.userVerification` | enum ("preferred") | yes | User verification (biometric or PIN) is preferred. |
| `data.authenticatorSelection.requireResidentKey` | boolean | yes | Always false. |
| `data.extensions` | object | yes | WebAuthn extensions requested. |
| `data.extensions.credProps` | enum (true) | yes | Asks the browser to report whether the credential is discoverable. |
| `meta` | object | yes | Request metadata: cost, timing and the request and trace ids. |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_SESSION_EXPIRED` | The session used to initiate passkey registration has expired; sign in again. |
| 401 | `K9O_MFA_REQUIRED` | An MFA challenge must be completed before passkey registration can begin. |
| 404 | `K9O_END_USER_NOT_FOUND` | The authenticated end-user record could not be found in this project. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/gate/passkeys/register/begin' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/gate/passkeys/register/begin', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`
  },
});
const { data, meta } = await res.json();
```

### @k9o/core

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


Canonical page: https://docs.kilimanjaro.dev/api-playground/identity-access/begin-passkey-registration
