Enrollment Flow

What Enrollment Is

Enrollment lets a user create an Emblem pass after your provider has already verified them. The user opts in, completes passkey creation on Emblem, and can skip verification next time through assertion.

A user who already has an Emblem pass (for example one that returned requires_verification with LEVEL_UPGRADE_REQUIRED because it held only L1) signs in with that pass on the enrollment page instead. Your verification is added to their existing pass: they keep one pass, your assertions keep the same subject for them, and their next sign-in satisfies the new level. You start enrollment and handle the callback exactly as for a new pass.

When To Use It

Use enrollment after:

• Your own verification flow completed successfully.
• You have the verification facts you need.
• The user chooses to create an Emblem pass.

Enrollment is not automatic. It is an explicit post-verification opt-in flow.

Prerequisites

You need:

• A provisioned client_id
• A registered redirect_uri
• A secret API key (emb_sk_...)

The same client_id used for assertion can be used for enrollment, but it must also be provisioned with credential issuance authority.

End-to-End Flow

Your verification completes successfully
User opts in to "Create an Emblem pass"
Your server  →  POST /api/v1/credentials/enroll/start  →  receives enrollment_url
Browser      →  redirects to Emblem                    →  user creates passkey
Browser      →  returns to your redirect_uri           →  with status or error

Start Enrollment

POST /api/v1/credentials/enroll/start records verification provenance and creates the enrollment session in one call.

import crypto from 'node:crypto'
import { createClient } from '@emblemapp/sdk'

const emblem = createClient({
  apiKey: process.env.EMBLEM_SECRET_KEY!,
})

const enrollment = await emblem.startEnrollment({
  client_id: process.env.EMBLEM_ASSERTION_CLIENT_ID!,
  redirect_uri: 'https://provider.example/emblem/enroll/callback',
  state: crypto.randomUUID(),
  provider: 'SAFEPASSAGE',
  verification_level: 'L1',
  external_verification_id: 'provider-verification-123',
  verified_at: new Date().toISOString(),
  external_user_ref: 'user-123',
  external_session_ref: 'journey-456',
})

res.redirect(enrollment.enrollment_url)

Request fields

Response fields

Callback Handling

Enrollment is terminal on the browser callback. There is no back-channel code exchange step.

Success callback

https://provider.example/emblem/enroll/callback?status=success&state=opaque_state

Failure callback

https://provider.example/emblem/enroll/callback?error=cancelled&error_code=USER_CANCELLED&state=opaque_state

Callback outcomes

The callback can arrive more than once for the same enrollment. If the user reopens a completed enrollment link (for example with Back or refresh, or after the first redirect did not reach you), Emblem sends the success callback again, so treat status=success idempotently for the same state. An expired enrollment link always returns SESSION_EXPIRED to your redirect_uri, even when it is opened after the session ended.

Current callback error mappings

Always validate state on callback before treating the flow as complete.

Idempotency

Enrollment start is idempotent on external_verification_id within the same client_id.

• If you retry with the same external_verification_id and the same immutable verification details, Emblem reuses the stored provenance and returns a fresh enrollment_url.
• If you retry with conflicting verification details, Emblem returns 409 IDEMPOTENCY_CONFLICT.

Treat external_verification_id as immutable per completed verification. The immutable details are provider, verification_level, and verified_at. Send the time the verification actually completed as verified_at, not a value that changes when your own record is updated; otherwise a retry (for example after the user returns to your page) is refused with 409 IDEMPOTENCY_CONFLICT and the user cannot create a pass.

Error Reference

Start enrollment errors

Notes

• redirect_uri must be registered on the authorization client.
• redirect_uri must not already include state, status, error, or error_code query params. Emblem owns those callback keys and will reject ambiguous enrollment callback URIs.
• Connect endpoints use secret-key server auth only.
• Enrollment requires separate issuance authority even if the same client is already approved for assertion.