> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth profiles

> Run API scenarios as different roles so Qodex can test authorization behavior. Configure identities for role and authorization checks.

# Auth profiles

Auth profiles let the same API scenario run as different identities.

Use them to test whether admins, regular users, viewers, unauthenticated clients, and invalid tokens get the right access.

## How they work

An environment can carry many named auth profiles. Each profile has its own credentials and login config. At run time, a scenario picks one profile and inherits that profile's token for every step.

A profile has two flavors:

* **API**: posts credentials to a login endpoint and extracts a token from the response.
* **UI**: drives Playwright through the login form and captures storage state (plus sniffs a bearer token from network traffic for the API fallback).

Three concrete examples on a `staging` environment:

| Profile name | type | What it logs in as |
| - | - | - |
| `admin` | api | A privileged account that can read and write everything |
| `user` | api | A regular account scoped to its own resources |
| `viewer` | api | A read-only account |

A scenario that tests IDOR can run once as one `user`, capture that user's `userId`, then run as a different `user` profile and try to read the first user's resource. The expected result is 403. If the API returns 200, the assertion fails and Qodex opens a critical finding.

## Precedence

For API steps, the runner picks an auth source in this exact order:

1. **Static `authToken`** on the environment, if set directly. Overrides everything.
2. **Cached bearer token** if the cache is still fresh (TTL 30 minutes).
3. **`api_login_config`** on the environment (or the chosen `auth_profile.login_config`). Run the login, extract the token.
4. **Browser fallback via `ui_login_steps`**. Drive Playwright through the login form, sniff the bearer token off the network.

The cache is per environment and per profile. Successful logins are cached for 30 minutes. Saving an environment clears the cache. Cached tokens are redacted in API responses.

For UI steps, the runner uses the cached storage state if fresh, otherwise runs `ui_login_steps`.

## Inspect a cached token and credentials

When you need to debug a request by hand, expand the profile on the environment's **Auth Profiles** list. The cached bearer token and the configured credentials, such as a client ID, are masked by default. Click **Show** to reveal a value, or **Copy** to copy it without revealing it on screen.

The refresh token and captured session cookies are never shown.

Use this only for short-lived inspection, such as confirming which role a request is using in the API Playground or comparing a failing scenario against a manual request. Treat the copied value like any other secret: do not paste it into docs, chats, issue trackers, or source control.

## Mint and test a token

For API auth profiles, click **Get token** on the profile after you configure the login request.

Qodex sends the profile's login request, extracts the token with the configured `tokenPath`, and stores the result in the same short-lived cache used by scenario runs. If the login request fails, the profile shows the failure so you can correct the URL, body, headers, credentials, or token path before a scenario depends on it.

This is the fastest way to confirm that a profile is ready for the [API Playground](https://qodex.ai/docs/api-testing-playground.md), authorization checks, and scheduled runs.

The **Token cache** section of the profile shows when the token was cached and when it expires. Click **Expire now** to mark the cached token expired, or **Force refresh** to clear it so the next scenario that needs auth runs the login again.

## Credentials must resolve

A credential or login config value can reference a variable, such as `${CLIENT_ID}`, only from the same environment the profile is saved in. An API login config can also reference the profile's own credential keys.

* **At save time**, Qodex refuses a profile that references a variable the environment does not define, and names the missing variable and the environment. Fix the variable name or add the variable to the environment, then save again.
* **At run time**, if a credential still carries an unresolved reference, the login does not start and the scenario fails with a message naming the problem. Qodex never sends an empty `Authorization: Bearer` header and then reports the resulting 401 as a bug in your API.

## Manage environments and auth profiles

Open **Environments** under **Context** in the sidebar to manage an environment, its variables, and its auth profiles.

To delete an environment, select it, click **Delete**, and confirm **Delete**. This cannot be undone. If you only need a variant, use **Duplicate** first so the hosts, variables, and login configuration are copied into a new environment.

To edit an auth profile, select the environment, open **Auth Profiles**, expand the profile, and click **Edit**. The dialog opens pre-filled with the profile's current settings, including profiles Qodex created from chat. Leave a secret field blank to keep the stored value. If the profile has settings the form does not show, the dialog lists them and keeps them when you save. Click **Duplicate** to create a variant under a new name.

To delete an auth profile, expand it and click **Delete**, then confirm **Delete profile**. The profile and its cached session are removed from this environment.

Scenarios that name the profile keep their reference, because a scenario refers to a profile by name and resolves it against whichever environment the run targets:

* A run in another environment that has a profile with the same name still signs in normally.
* If you re-add a profile with the same name to this environment, those scenarios resolve it again.
* Until then, a run of one of those scenarios in this environment errors with a message that the profile is missing, instead of running unauthenticated.

When editing variables in an environment, removing a row takes effect when you save the environment. Check that no scenario, Playground request, or auth profile still needs that variable before saving.

## Handle magic links and cookie-based sessions

Not every identity can sign in through an API token exchange. A UI auth profile can now manage an inbox-driven sign-in flow, including a magic link, and retain the browser session it establishes.

Use this for passwordless login, email verification, or an application that authenticates only with session cookies:

1. Configure the UI login steps for the profile, including the email wait step when the app sends a sign-in link.
2. Give the profile its own project inbox label so another profile cannot consume the same login message.
3. Let Qodex open the matching link and verify that the resulting browser session is signed in.

Qodex reuses a confirmed session when it remains valid. This avoids unnecessary magic-link emails and lets API requests stay authenticated when the application has no bearer token.

Keep the profile's credentials and the captured session private. Qodex does not expose session-cookie values in normal project responses.

## OAuth 2.0 profiles

For OAuth 2.0 flows Qodex cannot start on its own, create the profile yourself: click **+ New profile**, choose an API profile, and set **Login type** to **OAuth 2.0: Client Credentials** or **OAuth 2.0: Authorization Code (browser redirect)**.

An Authorization Code profile signs in through the provider in a popup when you click **Connect** (or **Reconnect** to mint a new refresh token). To pin the profile to one test account, fill in **Account to connect**. Qodex then asks the provider for that account and stores tokens only when that account signs in, even if your browser is signed in to the provider as someone else. The scope must include `openid profile email` so Qodex can read which account signed in. Leave the field blank to accept any account.

## The api\_login\_config shape

The HTTP login configuration tells Qodex how to exchange credentials for a token.

```json theme={null}
{
  "url": "${API_BASE_URL}/auth/login",
  "method": "POST",
  "headers": { "Content-Type": "application/json" },
  "body": {
    "email": "${AUTH_EMAIL}",
    "password": "${AUTH_PASSWORD}"
  },
  "tokenPath": "data.access_token"
}
```

What each field does:

* `url`: where to POST. Must resolve to an absolute URL after `${var}` substitution. Bare paths are rejected.
* `method`: usually `POST`. The runner accepts any HTTP verb.
* `headers`: any headers the login endpoint needs. Default `Content-Type: application/json`.
* `body`: the request body. Plain JSON for most APIs, form-encoded for legacy.
* `tokenPath`: dot-notation JSONPath into the response body. `data.access_token` reads `response.data.access_token`. The runner uses a small JSONPath subset, dots only. For exotic paths, write a postscript instead.

The token returned here becomes the cached bearer for every API step in scenarios that pick this profile.

## When this matters

The whole point of running tests as multiple identities is authorization correctness:

* **IDOR** (insecure direct object reference): a `user` profile should not be able to read another user's resources. Run the same scenario as two different `user` profiles, capture an ID from one, request it as the other, assert 403.
* **BOLA** (broken object-level authorization): same idea at the object level. List your orders as one user, then try to load one of those order IDs as another user.
* **Role escalation**: a `viewer` should not be able to write. Run the write scenarios as `viewer` and assert 403 across the board.
* **Endpoint-level auth gating**: an unauthenticated client should get 401 on protected routes. Use a profile with no token (or a deliberately invalid one) to assert that.

You cannot test these correctly with a single shared admin token. The token has to be missing, invalid, lower-privilege, or wrong for the resource on purpose.

## Sample environment with two profiles

```json theme={null}
{
  "name": "staging",
  "hosts": {
    "api": "https://staging.example.com",
    "ui": "https://app-staging.example.com"
  },
  "auth_profiles": [
    {
      "name": "admin",
      "type": "api",
      "credentials": {
        "AUTH_EMAIL": "admin@example.com",
        "AUTH_PASSWORD": "${ADMIN_PASSWORD}"
      },
      "login_config": {
        "url": "${API_BASE_URL}/auth/login",
        "method": "POST",
        "body": { "email": "${AUTH_EMAIL}", "password": "${AUTH_PASSWORD}" },
        "tokenPath": "access_token"
      }
    },
    {
      "name": "user",
      "type": "api",
      "credentials": {
        "AUTH_EMAIL": "user@example.com",
        "AUTH_PASSWORD": "${USER_PASSWORD}"
      },
      "login_config": {
        "url": "${API_BASE_URL}/auth/login",
        "method": "POST",
        "body": { "email": "${AUTH_EMAIL}", "password": "${AUTH_PASSWORD}" },
        "tokenPath": "access_token"
      }
    }
  ]
}
```

Same login endpoint, different credentials, different tokens.

## On the roadmap

> [!TIP]
>
> Broader OAuth2 support and clearer reconnect controls for expired credentials are planned.

## Related

> [card] [Scenarios](https://qodex.ai/docs/api-testing-scenarios.md)
>
> See where step.auth attaches.

> [card] [Chaining and postscripts](https://qodex.ai/docs/api-testing-chaining.md)
>
> Capture tokens from a login response.

> [card] [API Playground](https://qodex.ai/docs/api-testing-playground.md)
>
> Run requests with any auth profile.

> [card] [Auto-verification on save](https://qodex.ai/docs/api-testing-auto-verification.md)
>
> What gets checked the moment you save.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.