Skip to main content

insufficient-scope

Type URI: https://developer.risepeople.com/errors/insufficient-scope HTTP status: 403 Forbidden Format: application/problem+json (RFC 7807)

When this fires​

Your access token is valid, but doesn't carry the OAuth scope this endpoint requires. 403, not 401 — we know who you are; you just aren't permitted to do this.

Common cases:

  • You requested a narrow scope set when minting the token (e.g. only employees:read) and are now calling an endpoint that needs another (e.g. payroll:read).
  • Your OAuth app isn't configured for the scope at all, so the authorization server didn't issue it.
  • You're using a token issued for a different client whose scope set doesn't overlap.

Example response​

{
  "type":   "https://developer.risepeople.com/errors/insufficient-scope",
  "title":  "Insufficient Scope",
  "status": 403,
  "detail": "Token is missing required scope `payroll:read`.",
  "instance": "/v1/payroll/runs"
}

The detail field always names the specific scope that was missing.

How to fix it​

  1. Add the missing scope to your OAuth application — Settings → Developer → OAuth applications → your app → Scopes. The list of available scopes is on the Authentication page.
  2. Mint a new token that requests the new scope (Client Credentials) or re-authorize the user (Authorization Code with PKCE). Existing tokens don't pick up new scopes.
  3. Pass the new token on the failing request. The 403 should turn into a 200.

Refreshing an existing token won't help — the new token will inherit the old scope set.