> ## 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. # Request step-up scope > Initiate a step-up authentication flow for the given scope. Two reserved scopes (`prld:phone:register`, `prld:email:register`) drive the preformatted "register identifier" flow without consulting the customer's delegation hook. The identifier value must be supplied on `metadata.identifier`. ## OpenAPI ````yaml post /v1/session/stepup/request openapi: 3.1.1 info: title: Prelude Auth Frontend API version: 0.0.1 description: The Prelude Frontend API for Authentication and Session Management contact: email: support@prelude.so servers: - url: https://{appId}.session.prelude.dev description: Production server variables: appId: default: changeme description: The appID security: [] tags: - name: Login OTP description: Login and step-up via OTP (phone or email) - name: Login Email Password description: Login via email and password - name: Login OAuth description: Login via OAuth providers - name: Login SAML description: Login via SAML 2.0 SSO connections (Okta, Google Workspace) - name: Login Finalize description: Finalize a login flow and create a session - name: Login Migration description: Migrate sessions from a legacy authentication system - name: Session description: Session refresh and revocation - name: Session Management description: Authenticated session and identifier management - name: Step-Up description: Step-up authentication flow - name: Well-Known description: Public key discovery endpoints - name: Password description: Password compliancy and change password - name: Passkey Login description: >- Primary-factor (passwordless) sign-in via WebAuthn discoverable credentials - name: Passkey Management description: >- Register / list / rename / delete the authenticated user's passkey credentials paths: /v1/session/stepup/request: post: tags: - Step-Up summary: Request step-up scope description: | Initiate a step-up authentication flow for the given scope. Two reserved scopes (`prld:phone:register`, `prld:email:register`) drive the preformatted "register identifier" flow without consulting the customer's delegation hook. The identifier value must be supplied on `metadata.identifier`. operationId: stepUpRequestScope requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StepUpGrantScopeRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StepUpGrantScopeResponse' '400': description: Bad Request content: application/json: schema: oneOf: - $ref: '#/components/schemas/BadRequestError' - $ref: '#/components/schemas/ScopeNotAllowedError' - $ref: '#/components/schemas/InvalidMetadataError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/IdentifierAlreadyExistsError' '422': description: Unprocessable Entity content: application/json: schema: oneOf: - $ref: '#/components/schemas/StepUpNotConfiguredError' - $ref: '#/components/schemas/DirectScopeIdentifierMismatchError' '500': description: Internal Error content: application/json: schema: $ref: '#/components/schemas/InternalError' security: - accessTokenAuth: [] components: schemas: StepUpGrantScopeRequest: type: object properties: scope: allOf: - $ref: '#/components/schemas/Scope' description: | 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. metadata: type: object maxProperties: 5 propertyNames: pattern: ^[a-zA-Z0-9.\-_:]+$ maxLength: 12 properties: identifier: type: string maxLength: 320 description: | Required when `scope` is a register scope (`prld:phone:register` / `prld:email:register`). The phone number (E.164) or email address being registered. Phone numbers are normalized to E.164; emails are lowercased. additionalProperties: type: string maxLength: 32 description: >- 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: type: string description: The identifier of the dispatch from the front-end SDK. examples: - 123e4567-e89b-12d3-a456-426614174000 required: - scope StepUpGrantScopeResponse: type: object properties: status: type: string enum: - continue - review - block description: > 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. examples: - continue challenge_token: type: string description: >- The challenge token for the step-up flow (present when status is "continue" or "review"; absent when status is "block"). examples: - eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9... public_key_credential_request_options: $ref: '#/components/schemas/PublicKeyCredentialRequestOptions' BadRequestError: type: object properties: code: type: string enum: - bad_request type: type: string enum: - bad_request ScopeNotAllowedError: type: object properties: code: type: string enum: - scope_not_allowed type: type: string enum: - bad_request InvalidMetadataError: type: object properties: code: type: string enum: - invalid_metadata type: type: string enum: - bad_request UnauthorizedError: type: object properties: code: type: string enum: - unauthorized type: type: string enum: - unauthorized IdentifierAlreadyExistsError: type: object properties: code: type: string enum: - identifier_already_exists type: type: string enum: - conflict StepUpNotConfiguredError: type: object properties: code: type: string enum: - not_configured type: type: string enum: - unprocessable_entity DirectScopeIdentifierMismatchError: type: object properties: code: type: string enum: - direct_scope_identifier_mismatch type: type: string enum: - unprocessable_entity InternalError: type: object properties: code: type: string enum: - internal type: type: string enum: - internal Scope: type: string pattern: ^[a-zA-Z0-9.\-_:]+$ description: A scope identifier. examples: - transfer:write PublicKeyCredentialRequestOptions: type: object description: | 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. properties: challenge: type: string pattern: ^[A-Za-z0-9_-]+$ description: Base64url-encoded challenge bytes. timeout: type: integer description: Ceremony timeout in milliseconds. rpId: type: string description: Relying Party identifier. allowCredentials: type: array items: type: object properties: type: type: string enum: - public-key id: type: string pattern: ^[A-Za-z0-9_-]+$ description: Base64url-encoded credential id. transports: type: array items: type: string userVerification: type: string enum: - required - preferred - discouraged required: - challenge securitySchemes: accessTokenAuth: type: http scheme: bearer bearerFormat: JWT description: Access token obtained from session refresh ````