Adding passkeys via the API

Until now, every passkey in this service was created by a human, in their own browser, with the extension. That is still the default, and still the path with the fewest moving parts. The enrol scope adds a second one: an agent or a script that already drives a browser can add a passkey to a site — after the person has signed in to that site in the browser it drives.

Read that clause twice. The service does not hold a password, a cookie or a session, so it cannot get the browser past the site's login. What the enrol scope does is answer the site's *registration* ceremony once a signed-in page asks for one. The first login is still a human act; everything after it can be the agent's.

What enrol unlocks

The scope is labelled "Add passkeys" on the consent screen and the API-key form, and is off by default. Revoking — passkey_revoke, POST /v1/credentials/:id/revoke, POST /v1/subjects/:id/revoke — is a second scope, credentials:write ("Revoke passkeys"), also off by default, so a key that can add passkeys cannot remove them unless you said so.

The four steps

1. Get the human signed in. Open the site in the browser you drive and stop. Either the person signs in there themselves, or the site already has a session from a persistent profile. If there is a passkey for this site already, passkey_begin_signin gets you in as usual. If there is neither, say so — there is no tool that does this step.

2. Begin. Call passkey_begin_enrol({ domain, signinUrl?, userName? }) — with subjectId if the passkey belongs to one of your customers, and policy: { mode: "session", expiresAt } if it should sign unattended for a bounded window (30 days at most; silent is refused). You get a ticket, an expiresAt a few minutes out, and shim: a page script with the ticket and this service's origin baked in. Navigate the signed-in browser to the site's security settings — the page with its own "Add a passkey" button — and evaluate the shim there, as-is, before you click anything.

3. Click the site's button. The shim has replaced navigator.credentials.create(). When the site calls it, the page POSTs { ticket, origin, clientDataJSON, rpId, user } to this service itself, receives the attestation, and hands it to the site as if a local authenticator had made it. You carry nothing. Watch window.__apkEnrol.status in the page:

Or ask the server: passkey_enrol_status({ ticket }) reports unused, created, confirmed, withdrawn or expired, with the new credentialId and connector once created.

4. Report the verdict. The service cannot see whether the site accepted the passkey; the page's own success message is the only evidence. Call passkey_complete_enrol({ ticket, ok: true }) and the connector is confirmed. Call it with ok: false (and a detail saying what the site said) and the credential is withdrawn — revoked in the same transaction, so a passkey the site never registered does not linger as a live connector.

The shim, drawn

  agent's browser (signed in)                  Agent Passkey
  ───────────────────────────                  ─────────────
  site's "Add a passkey" page
   │
   │ 1. evaluate shim              ◄──────────  begin_enrol
   │    create() is now ours                    { ticket, shim }
   │
   │ 2. click "Add passkey"
   │    site calls create({rp,user,challenge})
   │
   │ 3. page POSTs {ticket, origin, ──────────►  POST /enrol/ticket
   │      clientDataJSON, rpId, user}            mint P-256 key
   │                                ◄──────────  { attestation }
   │
   │ 4. page hands attestation to the site
   │    site registers the public key
   │
   │ 5. __apkEnrol.status = "created"           GET /v1/enrol/:ticket
   │                                             → created
   │
   │ 6. site says "Passkey added"  ──────────►  POST /v1/enrol/complete
   │                                             → confirmed

The private key is generated at step 3 and never leaves the service. What crosses the wire is the attestation — the public half and a signature over it — which is what the site would have received from a local authenticator.

The direct path

A caller that runs the WebAuthn ceremony itself — a test harness, a headless runner with its own credential-handling — does not need the shim. passkey_enrol_direct({ domain, origin, userName, userHandle? }) returns the attestation in one call:

{ "credentialId": "…", "attestationObject": "…", "authData": "…",
  "publicKeyDer": "…", "transports": ["internal"], "credProps": { "rk": true } }

The caller hands those to the site in whatever shape the site's create() options expect. The connector is created immediately, in the same shape the ticket path produces; there is no confirm step, so if the site rejects it, call passkey_revoke yourself.

What the new passkey looks like

• It gets an approval-mode policy by default: a human is asked before every signature, until the owner changes it on the dashboard — or a bounded session policy if you asked for one at begin. Never silent.
• It is appended to the enrolling key's accounts, so the same key can sign in with it next. If that key is a session-mode key, the new credential inherits session mode.
• It appears on the dashboard's Passkeys page as "Added via API by <agent>", so the owner can see which of their passkeys a person made and which an agent did.
• A key with coverEnrolled (the default for keys holding enrol) is covered for it automatically; there is nothing to re-mint.
• passkey_revoke({ domain | credentialId }) (credentials:write) removes it. Every grant that covered it loses it at once; the audit rows stay.
• Signing many customers in? Bind each passkey to a subject at begin.

Honest limits

• The human signs in first. Nothing here gets a browser past a login. If the browser you drive has no session on the site, stop and ask the person.
• The site must accept a platform passkey. The attestation reports transports: ["internal"] and rk: true. A site that demands a roaming key, a specific attestation format, or enterprise attestation will refuse it, and ok: false is the right report.
• Second-factor-only sites stay out of reach. A passkey enrolled as a second factor can be enrolled this way, but signing in with it later still needs the password first, which this service does not hold. Check the site's notes before spending the ticket.
• One ticket, one credential. A ticket that has created does nothing on a second create(); mint another. A ticket expires in a few minutes, so do step 1 before step 2.
• Cross-origin iframes. The shim writes crossOrigin: false. A site whose "add passkey" flow runs inside a cross-origin frame will reject the clientDataJSON. Report it.