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>",
  "public_key_credential_request_options": {
    "challenge": "<string>",
    "timeout": 123,
    "rpId": "<string>",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "<string>",
        "transports": [
          "<string>"
        ]
      }
    ]
  }
}

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" or "review"; absent when status is "block").

Example:

"eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."

​
public_key_credential_request_options
object

WebAuthn PublicKeyCredentialRequestOptions in the WebAuthn Level 3 JSON form (binary fields are base64url-encoded). Present only when the step-up step the response advanced to is verify_passkey; pass it to navigator.credentials.get({ publicKey }). The frontend SDKs cache it keyed on the challenge id and run the assertion automatically.