Skip to main content
Step-up authentication provides an additional layer of security for sensitive operations.

​
What is Step-Up Authentication?

Step-up authentication requires users to re-authenticate (typically with MFA) before performing sensitive operations, even if they’re already logged in.

​
When is Step-Up Required?

Step-up authentication is required for:
  • Disabling SSO
  • Deleting custom domains
  • Regenerating MFA recovery codes
  • Changing tenant settings
  • Accessing audit logs
  • Break-glass operations

​
How It Works

  1. User attempts a sensitive operation
  2. API returns 403 Forbidden with requires_step_up: true
  3. User calls /api/v1/sessions/elevate with MFA code
  4. User receives elevated access token
  5. User retries the original operation with elevated token

​
Example Flow

1

Attempt Sensitive Operation

curl -X DELETE https://cp.gosentrix.io/api/v1/tenants/{id}/domains/{domain_id} \
  -H "Authorization: Bearer REGULAR_TOKEN"
Response: 403 Forbidden - Step-up authentication required
2

Elevate Session

curl -X POST https://api.gosentrix.io/api/v1/sessions/elevate \
  -H "Authorization: Bearer REGULAR_TOKEN" \
  -d '{"mfa_code": "123456"}'
Response: Elevated access token
3

Retry with Elevated Token

curl -X DELETE https://cp.gosentrix.io/api/v1/tenants/{id}/domains/{domain_id} \
  -H "Authorization: Bearer ELEVATED_TOKEN"
Response: 204 No Content (success)

​
Elevated Session Duration

Elevated sessions last 15 minutes from the time of elevation.

​
Best Practices

  • Always check for requires_step_up in error responses
  • Prompt users for MFA when step-up is required
  • Cache elevated tokens for the session duration
  • Clear elevated tokens on logout