How APIs know who you are
Most APIs want to know who is asking before they answer. This page explains the common ways a request proves that, in plain terms, and where each one goes in ApiWorkbench.
Two different questions
- Authentication: who are you? Failing it gets a
401 Unauthorized. - Authorization: are you allowed to do this? Failing it gets a
403 Forbidden.
A hotel key card is a fair picture. Having a valid card proves you are a guest (authentication). Which doors it opens is a separate matter (authorization).
API key
The simplest scheme. The service gives you a long secret string, and you send it with every request, in a header or in the query string:
GET /weather?city=Chennai
X-API-Key: 9f2c7a61b0e44d0bGood for server-to-server calls and simple public APIs. The key identifies an application, not a person.
Basic auth
A username and password, joined with a colon and encoded as Base64, in the Authorization header:
Authorization: Basic YWRhOnNlY3JldA==Encoded is not encrypted
Base64 is a way of writing text, not a lock. Anyone who sees that header can read the password. Basic auth is only safe over https.
Bearer token
You sign in once, and the server hands you a token: a string that stands for "this user, signed in, until this time". You then send the token with every request:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..."Bearer" means "whoever bears this token gets in", so a token must be guarded like a password. Tokens usually expire, after minutes or hours, and you sign in again or use a refresh token to get a new one.
Many tokens are JWTs (JSON Web Tokens): three Base64 pieces separated by dots. The middle piece holds readable claims such as the user id and the expiry time. A JWT is signed, so it cannot be altered, but it is not secret: do not put anything private in one.
This sign-in-then-send pattern is the one you will test most often:
1. POST /auth/login { email, password } -> 200 { "token": "abc..." }
2. GET /orders Authorization: Bearer abc... -> 200 [ ... ]In ApiWorkbench, a capture on step 1 saves the token into a variable, and step 2 uses it. The Shop API lab walks through exactly that.
OAuth 2.0
OAuth answers a harder question: how can an app act for you on another service without ever seeing your password? It is what happens when you choose "Sign in with Google".
The app sends you to the service's own sign-in page. You sign in there and approve what the app may do. The service sends the app a token limited to those permissions (its scopes). The end result is still a Bearer token; OAuth is the procedure for getting it.
The procedure comes in a few variants, called grant types:
| Grant type | Used when |
|---|---|
| Authorization code (with PKCE) | A person signs in through a browser. The usual choice |
| Client credentials | One server talks to another, with no person involved |
| Password | The app collects the username and password itself. Legacy; avoid |
| Implicit | Older browser apps. Legacy; avoid |
ApiWorkbench runs all four and refreshes tokens for you. See OAuth 2.0.
Where it goes in ApiWorkbench
Open the Auth tab of a request and choose a type. ApiWorkbench builds the header or parameter for you.
| You have | Choose | Guide |
|---|---|---|
| Nothing | No Auth | |
| A token | Bearer Token | Authorization |
| A username and password | Basic Auth | Authorization |
| A key | API Key | Authorization |
| A client id and an authorization server | OAuth 2.0 | OAuth 2.0 |
| Something rarer (Digest, NTLM, AWS, Hawk…) | The matching type | Other auth types |
A request can also inherit its auth from its folder or collection, so you set it once for a whole API.
Keeping secrets out of trouble
- Put secrets in variables, not in requests. Write
{{token}}in the request and keep the value in an environment. Then the saved request holds no secret. See Variables and environments. - Mark them secret. A secret variable is masked in editors, the Console, docs and reports.
- Think before you share. Check what an exported file contains before you send it to someone or commit it.
- Never paste a real token into a chat, a ticket or a screenshot. If you do, revoke it.
- Use test accounts for testing. Not your own, and never a customer's.
What a mock can do here
Mock Studio can require an Authorization header on any endpoint and answer 401 when it is missing. It does not check that the token is valid, only that one was sent, which is enough to test that your client sends it and handles a refusal. See Auth, CORS and project settings.
What you learned
- 401 means "who are you?", 403 means "not allowed".
- API keys, Basic auth and Bearer tokens all travel in the request, usually in a header.
- OAuth 2.0 is a way of obtaining a Bearer token without sharing a password.
- Secrets belong in variables.