Skip to main content
POST
/
v1
/
session
/
stepup
/
request
Request step-up scope
curl --request POST \
  --url https://{appId}.session.prelude.dev/v1/session/stepup/request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scope": "transfer:write",
  "metadata": {
    "identifier": "<string>"
  },
  "dispatch_id": "<string>"
}
'
{
  "challenge_token": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.prelude.so/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Access token obtained from session refresh

Body

application/json
​
scope
string
required

A scope identifier. Two reserved scopes drive the preformatted register-identifier flow: prld:phone:register (adds a phone number, OTP step verify_sms) and prld:email:register (adds an email address, OTP step verify_email). Register scopes require metadata.identifier and must be listed in the app's step-up allowed_scopes to be usable.

Pattern: ^[a-zA-Z0-9.\-_:]+$
Example:

"transfer:write"

​
metadata
object

Optional metadata (max 5 fields, keys max 12 chars, values max 32 chars; the reserved identifier key accepts up to 320 chars for register scopes).

Examples:
{ "amount": "500", "currency": "USD" }
{ "identifier": "+15551234567" }
​
dispatch_id
string

The identifier of the dispatch from the front-end SDK.

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

OK

​
status
enum<string>

The outcome of the step-up request. continue — scope granted immediately (session refreshed by the SDK). review — challenge created; the client must complete the returned steps. block — scope denied by the backend hook.

Available options:
continue,
review,
block
Example:

"continue"

​
challenge_token
string

The challenge token for the step-up flow (present when status is "continue").

Example:

"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."