Authentication Setup — API Key, Bearer Token, OAuth 2.0

Almost every real API requires some form of authentication. Postman's Authorization tab handles the most common schemes — API Key, Bearer Token, Basic Auth, OAuth 2.0 — without you needing to hand-craft headers. Set auth once at the collection level and every request inherits it. This lesson walks through each scheme, how to wire it up, when to use which, and the auto-refresh-token pattern that keeps a long-running suite working when tokens expire mid-run. The masterclass API Keys & Basic Auth, JWT Tokens, and OAuth 2.0 Flows lessons cover the concepts; this lesson covers the Postman wiring.

The Authorization tab

Open any request and click the Authorization tab — between Headers and Body. The Type dropdown lists every scheme Postman supports out of the box: No Auth, API Key, Bearer Token, Basic Auth, Digest Auth, OAuth 1.0, OAuth 2.0, Hawk, AWS Signature, NTLM, Akamai EdgeGrid.

You'll use four of those daily. The rest are situational.

Setting auth at the collection level

The right default is to set auth on the collection, not on each request. Right-click the collection → Edit → Authorization tab. Pick the type, configure it once. Every request in the collection then has its Authorization type set to "Inherit auth from parent" by default — meaning it uses the collection's setting.

When a specific request needs different auth (admin vs user, public vs authenticated), override on that request's Authorization tab.

This single decision saves you hundreds of edits over the life of a collection.

The four schemes you'll use most

API Key — the simple case

For an API that wants X-API-Key: <yourkey>:

1. Auth tab → Type: API Key.
2. Key: X-API-Key.
3. Value: {{apiKey}} — point at an environment variable, never paste the key directly.
4. Add to: Header (most APIs) or Query Params (some legacy or simple APIs).

Then in your environment, set apiKey (use the Current value column for the real key — the Initial value stays empty or has a placeholder so secrets don't sync to teammates).

Bearer Token — the most common modern setup

Bearer auth assumes you already have a token. Two paths to get one:

Manual paste — paste the token straight into the Token field once. Fine for ad-hoc work, terrible for repeatable tests because it expires.

Login request that extracts — a POST /login request whose Tests tab does:

const r = pm.response.json();
pm.collectionVariables.set("authToken", r.token);
pm.collectionVariables.set("tokenExpiresAt", Date.now() + 60 * 60 * 1000); // 1 hour

Then the collection's auth is Bearer Token with Token: {{authToken}} and every request inherits it. Run the login first, then run the rest of your collection — works for an hour without thought.

Basic Auth

For an admin endpoint that uses Basic:

1. Auth tab → Type: Basic Auth.
2. Username: {{adminUsername}}.
3. Password: {{adminPassword}}.

Postman base64-encodes username:password and sets Authorization: Basic <encoded> automatically. Set the username and password in your environment's Current value column.

Always check the show-password toggle next to the Password field — it masks the value in screenshots. Never put real Basic Auth credentials in the Initial value column (which syncs).

OAuth 2.0 — the full flow

The richest Postman auth helper. To wire up an OAuth 2.0 Authorization Code flow:

1. Auth tab → Type: OAuth 2.0.
2. Set the basics:
   • Token Name — a label so you can save and reuse this token.
   • Grant Type — Authorization Code, Authorization Code (with PKCE), Client Credentials, etc. Pick what your provider documents.
   • Callback URL — https://oauth.pstmn.io/v1/callback (Postman's hosted callback) or your own.
   • Auth URL — the provider's authorize endpoint.
   • Access Token URL — the provider's token endpoint.
   • Client ID and Client Secret — from the provider's developer console.
   • Scope — space-separated list of scopes you want.
3. Click Get New Access Token. Postman opens a browser, you log in to the provider, the provider redirects back with an auth code, Postman exchanges it for a token, and you're shown the token in a panel.
4. Click Use Token to attach it to the request. Postman stores the token under the Token Name; you can come back later and Use Token again without redoing the flow.

The token is then sent as Authorization: Bearer <token> automatically. Same shape as the simple Bearer case; the helper just got the token for you.

For Client Credentials (no user, just service-to-service), the same dialog skips the browser step — Postman exchanges client id+secret for a token directly.

Auto-refresh tokens for long runs

Tokens expire. A 30-minute Newman run with a 60-minute token is fine; an hour-long run isn't. The pattern from the pre-request scripts lesson handles this — at the collection level, before every request, check expiry and refresh if needed:

const tokenExpiry = pm.collectionVariables.get("tokenExpiry");
const now = Date.now();
 
if (!tokenExpiry || now > parseInt(tokenExpiry, 10)) {
    pm.sendRequest({
        url: pm.environment.get("baseUrl") + "/auth/refresh",
        method: "POST",
        header: { "Content-Type": "application/json" },
        body: {
            mode: "raw",
            raw: JSON.stringify({
                refreshToken: pm.collectionVariables.get("refreshToken")
            })
        }
    }, (err, res) => {
        if (err) {
            console.error("Token refresh failed:", err);
            return;
        }
        const data = res.json();
        pm.collectionVariables.set("authToken", data.token);
        pm.collectionVariables.set("tokenExpiry", (now + 59 * 60 * 1000).toString());
        console.log("Refreshed authToken — expires", new Date(now + 59 * 60 * 1000).toISOString());
    });
}

Drop this in once at Edit collection → Pre-request Script. Every request in the collection benefits — the script no-ops when the token is fresh, refreshes when it isn't.

Inheriting and overriding

Each request's Authorization tab has a special Type called "Inherit auth from parent". That's the default for new requests in a collection that has collection-level auth set. To override:

• Pick a different Type on the request itself — that auth wins for this request only.
• Or pick No Auth to send no credentials (e.g. for a public health-check endpoint).

A common pattern: the collection uses Bearer Token for the main user, but a POST Login request uses No Auth (you don't have a token yet — that's what the request is fetching).

Storing secrets safely

Three rules:

• Real secrets go in Current value, never Initial value. Initial values sync to the cloud and to teammates.
• Add the *.postman_environment.json to .gitignore if you commit collections — environments contain Current values when exported.
• Rotate any key you've pasted into a screenshot or Slack message. Once a credential leaves Postman it's potentially logged forever.

⚠️ Common mistakes

• Setting auth on every request individually. Hundreds of duplicate Bearer configurations is a maintenance nightmare. Use collection-level auth and let requests inherit; override only when needed.
• Pasting tokens directly instead of using {{authToken}}. The token expires next hour; the paste lives in the request forever. Always reference a variable that a script can refresh.
• Committing OAuth client secrets to Git. Postman happily exports them in environment files. Sanitise before committing or add the file to .gitignore.

🎯 Practice task

Wire up real auth. 25-35 minutes.

1. Set up Bearer auth at the collection level. In your JSONPlaceholder API Tests, right-click the collection → Edit → Authorization → Type: Bearer Token → Token: {{authToken}}. Save. Open any request → confirm its Authorization tab now shows "Inherit auth from parent".
2. Add a login leg. In a free reqres.in test — make a new request POST Login with URL https://reqres.in/api/login, body {"email":"eve.holt@reqres.in","password":"cityslicka"}. In Tests tab: pm.collectionVariables.set("authToken", pm.response.json().token);. Send. Open the eye-icon view and confirm authToken is set.
3. Make a follow-up request GET Users (https://reqres.in/api/users). It inherits the Bearer auth — it should send Authorization: Bearer <token>. Open the Postman Console after Send and confirm the request header.
4. Override on one request. Add GET Public Status to the collection. On its Authorization tab, change Type to No Auth. Send to https://reqres.in/api/users (works without auth too). Console: confirm no Authorization header was sent.
5. API Key example. Create a fresh request to a public-data API that uses API keys (e.g. openweathermap.org free tier). Set Authorization → Type: API Key → Key: appid, Value: {{owmKey}}, Add to: Query Params. Set the key in your environment's Current value only. Send.
6. OAuth 2.0 walkthrough. No real provider needed — just open the Authorization tab → pick OAuth 2.0 → click Get New Access Token. Read the dialog. Cancel out. Knowing the fields exist (Auth URL, Token URL, Client ID, Scope) is enough until you have a provider to test against.
7. Stretch: add the auto-refresh skeleton to your collection's pre-request script. Use a console.log("would refresh token here") inside the if instead of an actual pm.sendRequest. Run any request and verify the log fires when no tokenExpiry is set.

You can now wire up any of the four common auth schemes and keep tokens fresh through a long-running suite. The last lesson of this chapter covers the opposite situation — when you don't have a real backend at all, but still need to test against one.