Skip to main content
POST
Open a passkey registration session

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
clientEntityId
string
required

The end-user identifier to enroll.

Example:

"entity_01234567890abcdef"

idempotencyKey
string<uuid>
required

A unique key for this registration session. Replaying the same key for the same clientEntityId, spcCapable, embedOrigin, redirectUri, username, and displayName returns the original session unchanged. Using the same key with a different value for any of these fields returns 409. Omitting embedOrigin on a replay is not a conflict, and a retry may also omit username and displayName; supplied labels are compared after normalization (see username). Once the registration completes, the label check no longer applies.

Example:

"550e8400-e29b-41d4-a716-446655440000"

spcCapable
boolean
default:false

Whether this credential should be marked as eligible for Secure Payment Confirmation (SPC). Defaults to false. This flag is recorded permanently at enrollment and cannot be changed later.

embedOrigin
string

The origin of your page that embeds the passkey enrollment ceremony, for example https://app.example.com. It must exactly match one of the origins approved for your account (scheme, host, and port; no trailing slash or path). Send it on every call. It is required when more than one origin is approved for your account: without it, the request fails with 400. When only one origin is approved, omitting it uses that origin. A blank value, or one that matches none of your approved origins, also fails with 400. The passkey enrollment ceremony is bound to this origin: when it is embedded, it can only be completed inside a page on this origin, and it posts its result only to this origin. If this origin is removed from your approved origins before enrollment completes, the enrollment fails.

Required string length: 1 - 512
Example:

"https://app.example.com"

redirectUri
string

For a native application, your registered https app callback URI, exactly as registered — Circle matches it exactly, including case and any trailing slash. An unregistered or malformed value fails with 400 (error code 420068) and no frame token is issued. Don't send embedOrigin in the same request.

Required string length: 1 - 2048
Example:

"https://app.example.com/sca/callback"

username
string

A name for the passkey that the end user's device shows and keeps, and can sync across their devices. Use a masked identifier, not a full email address or phone number. The value is normalized (Unicode NFC) and trimmed; after normalization it must be non-blank, contain no control or invisible formatting characters, and be at most 64 UTF-8 bytes. If omitted, Circle uses the end user's full email address on file, or their clientEntityId.

Example:

"jo****@example.com"

displayName
string

A friendlier name for the passkey, such as Jo at Acme. Defaults to username. Same rules as username.

Example:

"Jo at Acme"

Response

Successfully opened a passkey registration session.

data
object