403/401 is returned (permissions and scopes)

Troubleshooting 403 401 Permissions Scopes

Symptom
The authorization flow succeeds, but calling the API returns 401 or 403.

The difference between 401 and 403

Code	Meaning
401 Unauthorized	The credentials are wrong, invalid, or expired. A token problem
403 Forbidden	Authentication succeeded, but there is no permission for that operation. A scope, role, or ownership problem

Typical 401 cases and what to do

Token expired (expired_token) → refresh with the refresh token
Token revoked (user disconnected the integration, etc.) → re-authorization flow
Malformed Authorization header → Bearer (with a single space) + token
Wrong environment (using a production token in staging) → check the environment

Typical 403 cases and what to do

Insufficient scope (insufficient_scope) → add the required scope and re-authorize
No store access permission → check that the app is not hitting resources of a store other than the one it is connected to
User-scope not reviewed (app_not_approved) → apply for review (see the separate article)
Insufficient role permission → the user at connection time does not have the required role (owner, etc.)
Plan restriction (plan_limit_exceeded) → the store side needs to upgrade its plan

Isolation steps

Check the error.code and message in the response
Record X-RR-Request-Id in your logs
If 401, hit /v1/me to check whether the token itself is valid (if it succeeds the token is fine; if you get 403 later on, it is a permission problem)
If 403, check the scope included in the current token (/v1/oauth/introspect)
If the required scope is not included, re-authorize

How to check scopes

curl -X POST https://receiptroller.io/oauth/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=$ACCESS_TOKEN&client_id=$CLIENT_ID&client_secret=$SECRET"

→ {
  "active": true,
  "scope": "store.read receipt.read",
  "client_id": "...",
  "exp": 1745740001
}

Related guides

Published: 2026-04-27 Updated: 2026-07-05

Back to help list