Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 30 ยท Sending Requests

Authentication: API keys, Basic, Bearer and OAuth 2.0

Learn how the Postman Authorization tab sends API keys, Basic credentials, bearer tokens and OAuth 2.0 tokens, how inheritance works, and how to read a JWT.

Most real APIs refuse to talk to strangers. Before they answer, they want to know who is calling (authentication) and, later, what that caller may do (authorization). In HTTP this proof almost always travels in a header or in the query string, so authentication is, in the end, just another part of the request you already know how to build.

Postman puts all of this into one place: the Authorization tab of a request, folder or collection. You pick a type, fill in a few fields, and Postman adds the right header or parameter when it sends the request. In this lesson you will learn what each common type puts on the wire, how to avoid repeating yourself with inheritance, how to read a JSON Web Token (JWT), and how the OAuth 2.0 flow fits together.

The real Postman app cannot run on this site. The Authorization tab and the OAuth window are described in read-only steps, and every runnable example here is a stand-in: plain JavaScript that builds the same headers Postman builds, so you can see exactly what is sent.

Four common ways to prove who you are

API key A secret string in a header or query parameter.
Basic Username and password, Base64 encoded.
Bearer token A token you got earlier, sent as is.
OAuth 2.0 A flow that hands out short-lived tokens.

All four end up as a header or a parameter on the request.

1 / 2

The Authorization tab

Open any request and click Authorization. The Auth Type dropdown offers No Auth, API Key, Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0 and several more specialised types. The fields below change with the type you choose. Postman shows a preview of what it will add, and the Console (the footer button) shows the final request with every header, including the ones it added for you.

A good habit: never type a real secret into these fields. Type a variable such as {{apiKey}} or {{token}} instead, and keep the value in an environment (see Environments and variables). That way the collection can be shared or exported without leaking anything.

API keys

An API key is a long random string the provider gave you. The provider decides where it must go, and Postman's API Key type covers both common places:

  • Add to: Header with a key name such as X-API-Key, producing X-API-Key: abc123.
  • Add to: Query Params with a name such as api_key, producing ...?api_key=abc123.

Headers are the better place. URLs end up in browser history, server logs and proxy logs, so a key in the query string leaks far more easily. Use the query form only when an API forces you to.

Basic authentication

Basic auth sends a username and password with every request. The client joins them with a colon, encodes the result with Base64, and sends:

HTTP
Authorization: Basic ZGVtbzpzM2NyZXQ=

Base64 is an encoding, not encryption. Anyone who sees the header can decode it in a second, so Basic auth is only acceptable over HTTPS. In Postman you type the username and password into the two fields and the encoding happens for you. Try it yourself in the stand-in below, together with the other header formats.

JS Build the authentication headers by hand

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real Postman does the same job with more care (it also handles special characters in user names and the Digest scheme), but the result on the wire is exactly this: one header or one parameter.

Bearer tokens

A bearer token is a string that grants access to whoever "bears" (carries) it. You obtain it somewhere else, for example by logging in, and then send it on every request:

HTTP
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

In Postman choose Bearer Token and put {{token}} into the Token field. The prefix Bearer (with the space) is added for you; do not type it yourself or the header will read Bearer Bearer ..., a very common mistake that produces a 401.

Because anyone holding the token can use it, bearer tokens are short-lived, and they must travel over HTTPS only.

Reading a JWT

Many APIs issue bearer tokens in the JSON Web Token format. A JWT is three Base64URL-encoded parts joined by dots:

TEXT
header.payload.signature
  • The header names the signing algorithm, for example {"alg":"HS256","typ":"JWT"}.
  • The payload holds claims: sub (subject, usually a user id), iss (issuer), exp (expiry, Unix seconds), iat (issued at) and any custom fields such as role.
  • The signature lets the server check that nobody changed the first two parts.

Notice what is missing: encryption. Header and payload are only encoded, so anyone can read them. Never put secrets in a JWT payload. Only the server, which knows the signing key, can verify the signature; as a tester you can still read the claims, which is very useful: "why do I get 401?" is often answered by an exp in the past.

Base64URL differs slightly from plain Base64: it uses - and _ instead of + and /, and drops the = padding. The stand-in below builds a token (with a fake signature, since signing is the server's job) and decodes it again.

JS Decode a JWT and check its expiry

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Online JWT decoders do the same thing, but do not paste production tokens into random web tools.

OAuth 2.0 in Postman

OAuth 2.0 solves a different problem: letting an app act for a user (or for itself) without ever seeing the user's password. Instead of a password, the app receives an access token with a limited scope and a short life, often together with a refresh token that can fetch a new access token later.

The flow depends on the grant type. The ones you meet in Postman:

  • Authorization Code (optionally with PKCE): the user signs in on the provider's page, the provider redirects back with a one-time code, and the app swaps the code for tokens. The standard for apps with a user.
  • Client Credentials: no user at all. The app proves itself with a client id and secret and gets a token. Common for server-to-server APIs and the easiest to test.
  • Password Credentials and Implicit: older flows, discouraged today and listed mainly for legacy APIs.

In the Authorization tab you choose OAuth 2.0, fill in the Auth URL (where users sign in), the Access Token URL (where codes become tokens), Client ID, Client Secret, Scope and the Callback URL, click Get New Access Token, finish the sign-in in the window that opens, and then click Use Token. Postman stores the token and sends it as a bearer header. Fields vary a little between Postman versions, so follow the labels you see.

sequenceDiagram
    participant U as User
    participant P as Postman
    participant A as Auth server
    participant R as API
    P->>A: 1. Open sign-in page (client id, scope)
    U->>A: 2. Sign in and approve
    A->>P: 3. Redirect with one-time code
    P->>A: 4. Exchange code (and secret) for tokens
    A->>P: 5. Access token (+ refresh token)
    P->>R: 6. Request with Authorization: Bearer token

The authorization code flow: the password is typed only on the auth server's page.

For a client-credentials flow, the exchange itself is a single request that you can also send by hand. It is shown here read-only, because it needs a real auth server:

HTTP
POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=my-app&client_secret={{clientSecret}}&scope=orders.read

A typical answer is JSON containing access_token, token_type (Bearer), expires_in (seconds) and perhaps scope. Later lessons show how a script can store the token in a variable and refresh it automatically (see Pre-request scripts).

Inheritance: set it once

If every request in a collection needs the same token, typing it into each request would be wasteful and fragile. Postman's default for a new request is Inherit auth from parent: the request uses the setting of its folder, and the folder uses the setting of its collection (see Collections, folders and requests). Change the token variable in one place and every request follows.

To make an exception, for example a public /health endpoint, set that request's type to No Auth. A more specific level always overrides a less specific one. The stand-in below walks up the tree the way Postman resolves it.

JS Resolve inherited auth

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • A 401 after a long break. The token expired. Read its exp, or fetch a new one.
  • 403 instead of 401. You are authenticated but not allowed; check the scopes or role claims.
  • Secrets in the collection. Use variables, and keep secret values out of shared environments.
  • Keys in the URL. They reach logs; prefer headers.
  • Mixed up auth levels. If a request behaves oddly, open the Console and look at the real headers that were sent.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a Basic authentication header contain?

    Basic auth joins the user name and password with a colon and Base64-encodes the result. That is reversible, so it must only be used over HTTPS.
  2. 2. You choose the Bearer Token type and type 'Bearer abc' into the Token field. What goes wrong?

    Postman adds the Bearer prefix itself, so you should enter only the token (or a variable holding it).
  3. 3. Which part of a JWT can anyone with the token read?

    A JWT is signed, not encrypted. Header and payload are readable by anyone, so never store secrets in them.
  4. 4. Which OAuth 2.0 grant type needs no human user at all?

    With client credentials the application authenticates as itself using a client id and secret, which suits server-to-server calls.
  5. 5. A request is set to 'Inherit auth from parent' and its folder has no auth of its own. Where does Postman look next?

    Requests inherit from their folder, and folders inherit from the collection, so the lookup walks up the tree.

Summary

  • The Authorization tab turns your settings into a header or query parameter; the Console shows the real result.
  • API keys belong in headers; Basic is Base64 of user:password and needs HTTPS; bearer tokens go in Authorization: Bearer <token>.
  • A JWT is header.payload.signature: readable by anyone, verifiable only by the server. Check exp when you get a 401.
  • OAuth 2.0 swaps a sign-in (or client credentials) for short-lived access tokens; Postman's "Get New Access Token" automates the flow.
  • Set auth once at collection or folder level and let requests inherit it; keep secrets in variables.

Next, learn how to keep dozens of requests tidy in Collections, folders and requests.