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.

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

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.

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.