Testing OAuth-Protected APIs
OAuth is more involved than a static API key — access tokens, scopes, and expiry all affect how a test request behaves. Here's what actually matters when testing against it.
Authentication covers OAuth alongside API keys and bearer tokens as one of the auth methods AlleForge supports on a request. This guide goes deeper into OAuth specifically — the concepts that actually cause test requests to fail, and how to reason about them.
What you're actually sending
However a token was obtained, what reaches the API on every request is the same thing: an access token, almost always sent as a bearer token in the Authorization header.
GET https://api.example.com/orders HTTP/1.1
Authorization: Bearer eyJhbGciOiJI...This is the part that matters for testing: once you have a valid access token, attaching it to a request works exactly like attaching any other bearer token — set it once as an environment variable, or configure it on a collection so every request in it inherits the same token automatically.
Where the token actually comes from
OAuth's authorization flow — redirecting a user to log in and consent, then exchanging a code for a token — is how a real application obtains that token in production. Testing an OAuth-protected API doesn't require reproducing that entire flow by hand: however you get a valid access token (your own account, a test/sandbox credential the API provider issues, or a token generated through the provider's own tooling), what you're testing with is the token itself, not the login flow that produced it.
Scopes
A token is often limited to specific scopes — read:orders, write:orders, and so on. A request failing with a 403 Forbidden even though the token is valid and unexpired usually means the token's scopes don't cover what the request is trying to do, not that the token itself is wrong. Check what scopes the token was actually issued with before assuming the request is broken.
Expiry
Access tokens expire — often in an hour or less. A request that worked yesterday and fails today with a 401 Unauthorized is frequently just an expired token, not a regression in the API or a mistake in the request. If you're testing an OAuth-protected API regularly, expect to refresh the token periodically rather than treating it as a one-time setup step.
Common failure modes, by status code
| Status | Usual meaning |
|---|---|
401 Unauthorized | Token missing, malformed, or expired |
403 Forbidden | Token valid, but missing the scope the request needs |
400 Bad Request (during a token exchange) | Malformed request to the token endpoint itself — wrong grant type, missing parameter |
Where this doesn't help
This covers testing with a token you already have. It doesn't walk through implementing an OAuth client, running a full authorization-code exchange, or handling token refresh inside an application — that's a different problem than sending authenticated test requests, and depends entirely on the specific OAuth provider's own flow and documentation.
See this in AlleForge
Open API Testing