Register an Identifier

Once a user is authenticated, you may want to let them attach a new identifier to their account: add a recovery phone number, switch to a new email address, enable a second login channel. Prelude exposes two reserved scopes that drive this flow end-to-end:

Scope	Identifier added	OTP step
`prld:phone:register`	`phone_number`	`verify_sms`
`prld:email:register`	`email_address`	`verify_email`

Register-identifier scopes are preformatted: Prelude runs the OTP challenge itself and does not call your delegation hook. You still need to declare the scope in your step-up configuration’s allowed_scopes with mode: "managed" so the frontend is permitted to request it. The client passes the identifier value on the request, Prelude validates it, runs the OTP challenge, and persists the identifier on the user’s profile when the challenge completes.

How it works

The new identifier is only attached to the user when the OTP step succeeds. If the user abandons the challenge or fails to enter a valid code, no change is made to their profile.

Prerequisites

A Prelude account with access to the Session API
An Application ID (appID) — see Applications
Step-up enabled on the application — see Step-Up Authentication. Register scopes reuse the step-up signing keys and JWKS, so step-up must be configured on the app
The register scope you want to expose declared in allowed_scopes on the step-up configuration with mode: "managed" (prld:phone:register and/or prld:email:register). The OTP step and the identifier write are handled by Prelude — no delegation hook is called for these entries
An OTP login configuration matching the identifier type you want to register (an SMS configuration for prld:phone:register, an email configuration for prld:email:register)

Register scopes must appear in allowed_scopes on the step-up configuration with mode: "managed". A request for a scope that is not allowed is rejected with scope_not_allowed before any OTP is sent. The managed mode is reserved for these two scopes and rejects any other scope at configuration time.

curl -X POST https://api.prelude.dev/v2/session/apps/${APP_ID}/config/stepup \
  -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "step_keys": [],
    "allowed_scopes": [
      { "scope": "prld:phone:register", "mode": "managed" },
      { "scope": "prld:email:register", "mode": "managed" }
    ]
  }'

Trigger the flow

The frontend SDK initiates the flow with a regular requestStepUp call. The new identifier is passed on the request metadata under the key identifier:

// Add a phone number
await session.requestStepUp({
  scope: 'prld:phone:register',
  metadata: { identifier: '+15551234567' }
});

// Add an email address
await session.requestStepUp({
  scope: 'prld:email:register',
  metadata: { identifier: 'user@example.com' }
});

Prelude returns status=review with a single OTP step keyed verify_sms or verify_email. From there the SDK drives the OTP step exactly like any other step-up challenge — see the Web SDK Step-Up guide for the full code path.

What Prelude does

Parse the value carried under metadata.identifier. Phone numbers are normalized to E.164; emails are lowercased and normalized.
Reject malformed values with a bad_request error before any OTP is sent.
Check uniqueness: if the identifier is already attached to a user (the requesting user or anyone else), the request is rejected with identifier_already_exists (HTTP 409). The OTP is never sent in this case.
Synthesize a single-use challenge with one OTP step. The grant lifetime and the step expiration are both 10 minutes (granted_for: 600).
Embed the canonical identifier on the challenge token so the value cannot be substituted by the client between stepup/request and the OTP completion.
On OTP success, attach the identifier to the user via the same path as the Add Identifier management endpoint. A user.identifier.created webhook event is emitted.

If a competing flow registers the same identifier between stepup/request and the OTP completion, the OTP check fails with identifier_already_exists and the identifier is not attached.

Constraints

Rule	Limit
`metadata.identifier`	Required. Phone numbers must be valid E.164. Email addresses must be syntactically valid. Maximum 320 characters (other step-up metadata values are capped at 32).
Grant lifetime	Fixed at 10 minutes. The grant uses `grant_mode: "single-use"` and is consumed by the identifier write itself; the client should not reuse the resulting access token for anything else.
Identifier ownership	The identifier must not already be attached to any user on the application. Use Delete Identifier first if you want to move an identifier between users.
OTP login configuration	An OTP configuration matching the identifier type must exist on the app. Without it, the OTP step cannot be sent.

Errors

Status	Code	Cause
400	`bad_request`	`metadata.identifier` is missing, malformed, or exceeds the metadata value limit.
409	`identifier_already_exists`	The value is already attached to a user — either at request time, or as a race when the OTP completes.

All other step-up errors (expired challenge, invalid token, replay, etc.) apply unchanged.

What’s next?

Step-Up Authentication

Full step-up overview, including custom scopes and the delegation hook.

Change Password

Companion preformatted flow for the prld:pwd:write scope.

Documentation

API Reference

How it works

Prerequisites

Trigger the flow

What Prelude does

Constraints

Errors

What’s next?

Step-Up Authentication

Change Password

​How it works

​Prerequisites

​Trigger the flow

​What Prelude does

​Constraints

​Errors

​What’s next?

Step-Up Authentication

Change Password

How it works

Prerequisites

Trigger the flow

What Prelude does

Constraints

Errors

What’s next?