Step-Up Hook Reference

When a user requests a scope grant via POST /v1/session/stepup/request, Prelude calls your step-up hook — the delegation_hook you registered for that scope in the step-up configuration when its mode is delegated. Your hook decides whether to grant the scope immediately, require a multi-step challenge, or block the request.

Hook request

Prelude sends a signed POST request to your hook URL with the following JSON body:

{
  "scope_requested": "transfer:write",
  "user_id": "usr_39CfbdV8AsXQwdphtbJe4yH07aF",
  "identifiers": [
    {
      "type": "email_address",
      "value": "user@example.com"
    },
    {
      "type": "phone_number",
      "value": "+33612345678"
    }
  ],
  "has_passkey": true,
  "signals": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "platform": "WEB",
    "ip": "203.0.113.42"
  },
  "metadata": {
    "amount": "500",
    "currency": "USD"
  }
}

Request fields

Field	Type	Description
`scope_requested`	`string`	The scope the user is requesting.
`user_id`	`string`	The Prelude user ID.
`identifiers`	`array`	The user’s identifiers (email addresses, phone numbers).
`identifiers[].type`	`string`	`"email_address"` or `"phone_number"`.
`identifiers[].value`	`string`	The identifier value.
`has_passkey`	`bool`	`true` when the user has at least one registered passkey credential on this app. Use it to route to `verify_passkey` when supported, falling back to an OTP step otherwise.
`signals`	`object`	Contextual signals from the user’s session.
`signals.user_agent`	`string`	The user’s browser or app user agent string.
`signals.platform`	`string`	The platform (e.g. `"WEB"`, `"ANDROID"`, `"IOS"`).
`signals.ip`	`string`	The user’s IP address.
`metadata`	`object`	Optional metadata passed by the frontend when requesting the scope. Max 5 fields, keys max 12 characters, values max 32 characters.

Request headers

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`Prelude-SessionStepUpHook/1.0`
`X-Webhook-Signature`	Base64 URL-encoded RSASSA-PSS SHA-256 signature of the request body.
`X-Webhook-Signature-Key-Id`	The ID of the signing key used to produce the signature.

Request signature

The hook request is signed using the same mechanism as webhooks. Verify the X-Webhook-Signature header using the public key matching the X-Webhook-Signature-Key-Id from your application’s JWKS endpoint.

Hook response

Your endpoint must return a JSON response with a verdict.

Grant immediately

Return status: "continue" to grant the scope without any challenge:

{
  "status": "continue",
  "granted_for": 3600,
  "grant_mode": "session-bound"
}

Require a challenge

Return status: "review" with one or more steps the user must complete:

{
  "status": "review",
  "granted_for": 180,
  "grant_mode": "single-use",
  "steps": [
    {
      "order": 1,
      "key": "verify_sms",
      "expiration_duration": 600
    },
    {
      "order": 2,
      "key": "kyc_review",
      "expiration_duration": 300
    }
  ]
}

Block the request

Return status: "block" to deny the scope entirely:

{
  "status": "block"
}

Response fields

Field	Type	Required	Description
`status`	`string`	Yes	`"continue"`, `"review"`, or `"block"`.
`granted_for`	`integer`	Yes (when `continue` or `review`)	Duration in seconds for which the scope is granted. Must be between 0 and 86400 (24 hours).
`grant_mode`	`string`	Yes (when `continue` or `review`)	`"single-use"` or `"session-bound"`. See below.
`steps`	`array`	Yes (when `review`)	The steps the user must complete, in order. Must not be empty when status is `review`. Must not be present when status is `continue` or `block`.
`steps[].order`	`integer`	Yes	The position of this step in the sequence (starting from 1).
`steps[].key`	`string`	Yes	The step identifier. Use `"verify_sms"` or `"verify_email"` for Prelude-owned steps, or a custom key you registered in the step-up configuration.
`steps[].expiration_duration`	`integer`	Yes	Time in seconds the user has to complete this step. Must be between 0 and 86400 (24 hours).

Grant modes

Mode	Behavior
`single-use`	The scope is attached only to the next access token. It is not persisted on the session. `granted_for` must be at least 1 second.
`session-bound`	The scope is stored on the session and included in every subsequent refresh for `granted_for` seconds. If `granted_for` is less than 1, it defaults to 600 seconds (10 minutes).

Response constraints

Rule	Limit
Maximum response body size	64 KB
`granted_for` range	0 to 86400 seconds (24 hours). Cannot be negative.
`steps` with `review`	Must contain at least one step.
`steps` with `continue` or `block`	Must not be present.
Step `key` format	Only `a-z`, `A-Z`, `0-9`, and `.-_:` characters.
Step `expiration_duration` range	0 to 86400 seconds (24 hours). Cannot be negative.

Response HTTP status

Your hook must return HTTP 200 with the JSON body. Any non-200 response or timeout (5 seconds) will cause the step-up request to fail.

Monitoring hook failures

When a call to your delegation hook fails — because the request could not be completed, the response had a non-2xx status code, or the body was malformed — Prelude emits a step_up.hook_failed webhook event with a reason field identifying the failure category. Subscribe to this event to alert on hook outages or misconfiguration.

Example implementation

Here is a minimal Node.js example of a step-up hook:

app.post("/hooks/stepup", (req, res) => {
  const { scope_requested, user_id, signals, metadata } = req.body;

  // Block requests from unknown IPs
  if (!isKnownIP(signals.ip)) {
    return res.json({ status: "block" });
  }

  // High-value transfers require SMS verification + KYC
  if (scope_requested === "transfer:write" && parseInt(metadata?.amount) > 1000) {
    return res.json({
      status: "review",
      granted_for: 120,
      grant_mode: "single-use",
      steps: [
        { order: 1, key: "verify_sms", expiration_duration: 600 },
        { order: 2, key: "kyc_review", expiration_duration: 300 }
      ]
    });
  }

  // Low-risk operations: grant directly
  return res.json({
    status: "continue",
    granted_for: 3600,
    grant_mode: "session-bound"
  });
});

Custom steps and verification tokens

If your hook returns custom step keys (anything other than verify_sms or verify_email), your backend must issue verification tokens to advance the challenge. See Custom Steps for the full verification token format, requirements, and code examples.

Documentation

API Reference

Hook request

Request fields

Request headers

Request signature

Hook response

Grant immediately

Require a challenge

Block the request

Response fields

Grant modes

Response constraints

Response HTTP status

Monitoring hook failures

Example implementation

Custom steps and verification tokens

​Hook request

​Request fields

​Request headers

​Request signature

​Hook response

​Grant immediately

​Require a challenge

​Block the request

​Response fields

​Grant modes

​Response constraints

​Response HTTP status

​Monitoring hook failures

​Example implementation

​Custom steps and verification tokens

Hook request

Request fields

Request headers

Request signature

Hook response

Grant immediately

Require a challenge

Block the request

Response fields

Grant modes

Response constraints

Response HTTP status

Monitoring hook failures

Example implementation

Custom steps and verification tokens