---
slug: auth/passkey/enroll/start
version: "0.2"
title: Auth — Passkey Enroll (start)
summary: An authenticated subject asks the auth service to begin a WebAuthn registration ceremony so a new passkey can be bound to their VID.
status: draft
targetFrameworkVersion: "0.5.0"
category: authentication
keywords:
  - auth
  - passkey
  - webauthn
  - enroll
  - registration
  - fido2
authors:
  - Glenn Gore (https://github.com/stormer78)
parties:
  - role: Subject
    requirement: REQUIRED
    member: issuer
  - role: Auth service
    requirement: REQUIRED
    member: recipient
proofRequirement:
  requirement: REQUIRED
  rationale: Binding a passkey to a subject is a high-trust assertion. Requiring a verified proof on the start ceremony prevents an opportunistic actor with a captured token from registering a credential they control against the legitimate subject's VID.
sideEffects:
  level: none
  rationale: "Begins a WebAuthn registration ceremony and returns options; no durable binding yet."
exposure:
  discloses: none
  actsAsSubject: false
errorCodes:
  - code: auth/passkey/enroll/start:maxCredentialsReached
    meaning: The subject already has the maximum number of passkeys this auth service is configured to bind. `details.limit` MAY carry the cap.
    retryable: false
    detailsSchema:
      type: object
      additionalProperties: false
      properties:
        limit: { type: integer, minimum: 0 }
  - code: auth/passkey/enroll/start:enrollmentNotSupported
    meaning: This auth service does not accept passkey enrollment (for example, a deployment that mandates an external IdP).
    retryable: false
  - code: auth/passkey/enroll/start:reauthUnavailable
    meaning: The consumer requires re-authentication to add an authenticator but cannot mount a ceremony against the subject's existing credentials. Recovery is out of band.
    retryable: false
related:
  - auth/passkey/enroll/finish
  - auth/passkey/list
  - auth/passkey/revoke/start
  - auth/passkey/login/start
  - auth/passkey/login/finish
---

## Abstract

The **Auth — Passkey Enroll (start)** Trust Task is the first leg of a WebAuthn registration ceremony. The subject — already authenticated via `auth/authenticate` or another mechanism — asks the auth service for `PublicKeyCredentialCreationOptions`. The subject's user agent hands the options to `navigator.credentials.create({ publicKey })`, and the resulting attestation is returned via [`auth/passkey/enroll/finish/0.2`](../../finish/0.2/spec.md).

The framework `proof` is REQUIRED. The auth service binds the issued `enrollmentId` to the producer's VID server-side; a finish call carrying a credential from a different subject MUST fail.

## Changes from 0.1

**Added `uvOptions` to the response** (optional), and its counterpart `uvCredential` to [`enroll/finish/0.2`](../../finish/0.2/spec.md). The framework target moves to 0.2.

0.1 modelled enrollment as a single registration ceremony authorized by the `proof`. That is right for the *first* passkey, where the proof is the only credential the subject has. It is not right for a subsequent one, because adding an authenticator to an account that already has one is a privilege escalation available to anyone holding a token: enroll silently, and you have durable access that survives the subject changing everything else.

0.2 lets the consumer demand that an **existing** authenticator authorize the addition, in the same round-trip. `uvOptions` is optional precisely because the first enrollment cannot satisfy it — there is nothing enrolled to verify against.

**Compatibility.** A 0.1 producer talking to a 0.2 consumer that issues `uvOptions` will fail at finish, since it cannot return an assertion it never obtained. That is the intended outcome: the alternative is a consumer silently dropping a control it decided it needed. Consumers introducing re-authentication **SHOULD** announce it before enabling it.

## Status of this Document

This is a **draft** *Trust Task specification* per [SPEC.md §5.3](/SPEC.md#53-maturity-levels); the schema **MAY** change without notice.

## Conformance

[[RFC2119]](https://www.rfc-editor.org/rfc/rfc2119) and [[RFC8174]](https://www.rfc-editor.org/rfc/rfc8174) key-word conventions apply.

A conforming **producer** **MUST**:

1. Emit a *Trust Task document* whose `type` is `https://trusttasks.org/spec/auth/passkey/enroll/start/0.2`, with itself as `issuer` and the auth service as `recipient`.
2. Include a verified `proof`.
3. **MAY** include a `payload.deviceLabel` so the credential is identifiable in subsequent listing / revocation flows.

A conforming **consumer** **MUST**:

1. Verify the `proof` and identify the producer's VID.
2. Generate a fresh server-side `enrollmentId` and bind it to:
   - The producer's VID.
   - The challenge embedded in `options.challenge`.
   - An expiry (RECOMMENDED 5 minutes).
3. Return `PublicKeyCredentialCreationOptions` with:
   - `rp.id` set to the auth service's relying-party identifier.
   - `user.id` set to a stable opaque user handle for the producer's VID (NOT the VID itself, per WebAuthn's privacy guidance — `user.id` SHOULD be a per-RP-per-subject hash or random-mapped identifier).
   - `pubKeyCredParams` containing at least one algorithm the consumer accepts. Ed25519 (`alg: -8`) is RECOMMENDED.
4. Refuse with `auth/passkey/enroll/start:maxCredentialsReached` if the subject is at the consumer's credential cap.
5. Decide whether re-authentication is required. A consumer that requires it **MUST** also return `uvOptions` — `PublicKeyCredentialRequestOptions` over the subject's **existing** credentials, with `userVerification: "required"` — and **MUST** bind that challenge to the same `enrollmentId`. A consumer **SHOULD** require it whenever the subject already has at least one credential.

A conforming consumer **MUST NOT** return `uvOptions` for a subject with no enrolled credentials: there is nothing to verify against, and a challenge that cannot be satisfied is indistinguishable to the producer from a broken service.

## Definitions

* **Subject.** The party enrolling a passkey; identified by `issuer`.
* **Auth service.** The WebAuthn relying party; identified by `recipient`.
* **enrollmentId.** Opaque correlation handle between the start and finish ceremonies; produced by the consumer.
* **PublicKeyCredentialCreationOptions.** WebAuthn dictionary; see [`_shared/0.1/webauthn.schema.json#CredentialCreationOptions`](../../../../_shared/0.1/webauthn.schema.json).

## Payload

`payload.deviceLabel` — optional human-readable credential name.

`payload.ext` — extension slot per [SPEC.md §4.5.1](/SPEC.md#451-the-ext-extension-member).

## Examples

### Authenticated subject enrolls a new device

```json
{
  "id": "11111111-aaaa-bbbb-cccc-222222222222",
  "type": "https://trusttasks.org/spec/auth/passkey/enroll/start/0.2",
  "issuer": "did:web:alice.example",
  "recipient": "did:web:auth.example",
  "issuedAt": "2026-05-23T12:00:00Z",
  "payload": {
    "deviceLabel": "Alice's MacBook Pro"
  },
  "proof": { "…": "…" }
}
```

## Response

A success *response* document carries `type: https://trusttasks.org/spec/auth/passkey/enroll/start/0.2#response`. Payload: `{ enrollmentId, options }`, plus `uvOptions` when the consumer requires re-authentication.

### Successful start

```json
{
  "id": "33333333-dddd-eeee-ffff-444444444444",
  "type": "https://trusttasks.org/spec/auth/passkey/enroll/start/0.2#response",
  "threadId": "11111111-aaaa-bbbb-cccc-222222222222",
  "issuer": "did:web:auth.example",
  "recipient": "did:web:alice.example",
  "issuedAt": "2026-05-23T12:00:01Z",
  "payload": {
    "enrollmentId": "enr_1a2b3c4d5e6f7890",
    "options": {
      "challenge": "Zm9vYmFyYmF6cXV4",
      "rp": { "id": "auth.example", "name": "Auth Example" },
      "user": {
        "id": "dXNyXzhmMmMxZDRlOWE3YjMwNTY",
        "name": "alice",
        "displayName": "Alice"
      },
      "pubKeyCredParams": [
        { "type": "public-key", "alg": -8 },
        { "type": "public-key", "alg": -7 }
      ],
      "timeout": 60000,
      "attestation": "none",
      "authenticatorSelection": {
        "residentKey": "preferred",
        "userVerification": "preferred"
      }
    }
  }
}
```

### Adding a second device, with re-authentication

The same response, for a subject who already has a passkey. `options` is unchanged; `uvOptions` is the added half, and its `allowCredentials` lists what the subject already holds.

```json
{
  "id": "55555555-eeee-ffff-0000-666666666666",
  "type": "https://trusttasks.org/spec/auth/passkey/enroll/start/0.2#response",
  "threadId": "11111111-aaaa-bbbb-cccc-222222222222",
  "issuer": "did:web:auth.example",
  "recipient": "did:web:alice.example",
  "issuedAt": "2026-07-27T12:00:01Z",
  "payload": {
    "enrollmentId": "enr_9e8d7c6b5a493827",
    "options": {
      "challenge": "ZW5yb2xsLWNoYWxsZW5nZQ",
      "rp": { "id": "auth.example", "name": "Auth Example" },
      "user": {
        "id": "dXNyXzhmMmMxZDRlOWE3YjMwNTY",
        "name": "alice",
        "displayName": "Alice"
      },
      "pubKeyCredParams": [{ "type": "public-key", "alg": -8 }],
      "excludeCredentials": [
        { "type": "public-key", "id": "q1w2e3r4t5y6u7i8o9p0" }
      ]
    },
    "uvOptions": {
      "challenge": "cmVhdXRoLWNoYWxsZW5nZQ",
      "rpId": "auth.example",
      "userVerification": "required",
      "allowCredentials": [
        { "type": "public-key", "id": "q1w2e3r4t5y6u7i8o9p0", "transports": ["internal"] }
      ]
    }
  }
}
```

The two challenges are distinct and both bound to the `enrollmentId`. Reusing one value for both would let a single ceremony's output satisfy the other check.

## Security & Privacy

**Re-authentication closes the silent-enrollment path.** Without it, a captured token is enough to bind an attacker-controlled authenticator to the subject's VID — access that outlives the token, survives a password change, and looks exactly like a legitimate device in [`auth/passkey/list`](../../../list/0.1/spec.md). Requiring an existing authenticator to authorize the addition means a stolen token alone cannot grow into durable access.

**Distinct challenges.** `options.challenge` and `uvOptions.challenge` **MUST** differ and **MUST** both be bound to the `enrollmentId`. Sharing a value collapses two ceremonies into one, and an attacker who can drive either can then satisfy both.

**user.id privacy.** WebAuthn's `user.id` is visible to roaming authenticators. Consumers MUST NOT use the producer's VID directly here; use a per-RP opaque mapping so a credential exported from the authenticator doesn't leak the VID outside the relying party.

**Challenge binding.** The `options.challenge` MUST be bound server-side to the `enrollmentId` and the producer's VID. A finish call presenting a different challenge MUST fail; this prevents replay of harvested attestations from other ceremonies.

**Algorithm policy.** The consumer's `pubKeyCredParams` ordering signals preference. Consumers SHOULD include only algorithms they accept; producers' authenticators will pick the first match.

**Attestation.** `attestation: "none"` is appropriate for most deployments — privacy-preserving and good enough for binding. Consumers operating under regulatory regimes that require attestation (FIDO2 enterprise contexts) MAY set `"direct"`, but should be aware this reveals authenticator-make/model.

The optional `ext` extension is part of the signed surface.

**Free text.** Four members of this exchange are free text and are now bounded.
`deviceLabel` (256) is the subject's own display name for the credential; the
consumer **retains** it with the credential and surfaces it on every later
credential listing, which is what it is for. The WebAuthn entity names inside
`options` — `rp.name`, `user.name` and `user.displayName` — are bounded at 64
each, the length [WebAuthn's user entity](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialuserentity)
tells authenticators to truncate to, so a longer value would be silently cut on
the device rather than carried. All three are consumer-authored and are read by
the *authenticator*, which may store them and redisplay them at future
ceremonies on hardware the consumer does not control — that is the retention
that matters here, and it is outside this exchange. None of the four is trusted
input to any decision: they are rendering material, and a consumer MUST NOT
derive identity from them.

