v3
latestOpenAPI 3.1.02026-07-311,4541,5202.3 MBauthentication
Auth Jwt Scope Create
Step-up scope change — Phase 5 of the staff step-up auth rollout.
One endpoint, both directions. Caller submits the desired session_scope value; the server validates, mints a new JWT carrying that scope, and returns it. Models OAuth 2.0 Token Exchange (RFC 8693). Replaces the originally-planned two endpoints (/scope-up/ + /scope-down/) — they were the same operation with opposite signs.
Validation gates differ by direction:
- Elevating (non-empty scope): requires reason in the body AND a fresh is_password_recently_verified flag (from the Phase 4 password-verify endpoint, 5-min sudo window).
- Narrowing (empty scope): no extra gate. Narrowing is always safe and reversible.
The OLD JWT remains cryptographically valid until its exp. Caller is responsible for replacing it client-side. Instant invalidation comes in Phase 7 (JTI denylist).
See implementation_logs/security/staff_step_up_auth_design.md §5.
post/auth/jwt/scope/
Headers
Authorizationstring required
JWT access token or Respan API key
Response
No response body
AuthenticationAuthJwtScopeCreateResponse200 required
Empty response body