Authentication

Overload reads auth config directly from your Postman collections. It supports 4 auth types, inherits auth through folder hierarchies, and supports variables.

Overview

When you export a Postman Collection v2.1, it includes the authentication settings. Overload parses these settings and applies them to your HTTP requests automatically. You don't need to manually configure auth headers in Overload if they are set up in Postman.

Bearer Token

How it works: Automatically adds an Authorization: Bearer {token} header to the request.

In Postman, select Bearer Token and enter your token. You can use variables like {{api_token}} in the token field.

Using Variables:

If your token is saved as {{api_token}} in Postman, you can override it at runtime via the CLI:

overload run --collection api.json --pattern burst --var api_token=my_secret_token_123

Basic Auth

How it works: Takes the username and password, Base64 encodes them, and adds an Authorization: Basic {encoded} header.

In Postman, select Basic Auth and fill in the username and password fields. Both fields support variable substitution, e.g., {{db_user}} and {{db_pass}}.

API Key

How it works: Adds a custom key-value pair either as an HTTP header or as a URL query parameter.

In Postman, select API Key. Provide the key (e.g., X-API-Key), the value, and select the location (Header or Query Params).

• Header placement: Overload will add headers[key] = value.
• Query placement: Overload will append ?key=value to the request URL.

OAuth2 Client Credentials

How it works: Overload automatically fetches an OAuth2 access token before the load test starts and caches it. It adds the Authorization: Bearer {token} header to requests.

Overload implements the Client Credentials flow.

In Postman, select OAuth 2.0. You must configure:

• Access Token URL
• Client ID
• Client Secret

When you start a test in Overload, the `prepare_collection_auth()` function runs. It makes a request to the Token URL using `grant_type=client_credentials`. The received token is cached and stored in the variable context as _oauth2_access_token. The token is automatically refreshed 30 seconds before it expires.

Auth Inheritance

Postman has a powerful auth inheritance model, and Overload implements it fully:

1. Collection Level: Auth set on the root collection applies to all requests.
2. Folder Level: Auth set on a folder overrides the collection auth, applying to all requests inside that folder.
3. Request Level: Auth set on a specific request overrides any inherited auth.

The parser automatically flattens the nested structure and ensures each request gets the correct, resolved auth configuration.

Auth with Variables (Best Practice)

You should never hardcode production tokens or passwords in your Postman collection files.

Instead, use variables in Postman (e.g., {{prod_token}}). When you run Overload, inject the real credentials using runtime overrides (--var) or environment files.

Example CI/CD workflow:

- name: Run Load Test
  run: overload run --collection api.json --var prod_token=${{ secrets.PROD_API_TOKEN }}

This ensures your load test definitions remain safe to commit to version control, while credentials stay protected in your CI platform's secrets manager.