Cannot obtain a token (authentication error)
Troubleshooting
Token
Authentication
OAuth
Symptom
The OAuth token endpoint (
The OAuth token endpoint (
/oauth/token) returns 4xx, and you cannot obtain an access token.
Main errors and what to do
| error | Cause | What to do |
|---|---|---|
invalid_client | The client ID / secret is wrong | Check in the developer portal; consider regenerating |
invalid_grant | The authorization code is expired, already used, or invalid | Start over from the authorization flow |
redirect_uri_mismatch | Does not match the registered URI | Check case, trailing slash, and port all match |
invalid_scope | The requested scope is not permitted for the app | Check the scopes in the app settings |
unauthorized_client | The app cannot use that grant type | Check the app type setting |
unsupported_grant_type | The grant_type parameter is invalid | authorization_code or refresh_token |
Isolation checklist
- ☐ Are the client ID / secret not mixed up between production and development?
- ☐ Did you not regenerate the secret recently?
- ☐ Are you exchanging the authorization code within 10 minutes of obtaining it?
- ☐ Are you not trying to use the same authorization code twice?
- ☐ Does
redirect_uriexactly match the one used in the authorization request? - ☐ Is the request
Content-Type: application/x-www-form-urlencoded? - ☐ Are the parameters in the body rather than the query?
Common mistakes
Sending JSON
The OAuth token endpoint requires application/x-www-form-urlencoded. Sending JSON results in invalid_request.
Sending client credentials both in Basic auth and in the body
Pick one. Sending both can result in invalid_request.
Forgetting to URL-encode the secret
If the secret contains symbols, URL encoding is required.
Related guides
Published: 2026-04-27
Updated: 2026-07-05
Category
Tags
API (22)
OAuth (15)
Android (10)
iOS (9)
Webhook (6)
Troubleshooting (5)
api (5)
App registration (4)
POS Integration (4)
Reference (4)
Related articles
-
403/401 is returned (permissions and scopes)How to isolate the cause when an API call returns 401 or 403. Explains the typical cases: invalid token, insufficient scope, no store access permission, and User-scope review not passed.
-
The developer portal is not shown while on the Free planWhat to check when the ReceiptRoller developer portal is not shown. Explains what to do when your plan is Free, switching business accounts, and the timing of when the display updates.
-
Webhook is not being deliveredHow to isolate the cause when a Webhook does not reach your receiving endpoint. Walks through checking, in order, the endpoint settings, subscribed events, reachability, signature-verification failures, and firewalls.
-
app_not_approved is returned for User-scope callsWhat to check when using a User-scope results in an app_not_approved error. Explains development with a sandbox slot, applying for review, and the flow from sandbox to production.