v3

latestOpenAPI 3.1.02026-07-311,4541,5202.3 MB
authentication

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