> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testsprite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto-Auth (Pro)
> Configure a login flow once and TestSprite fetches a fresh token before every backend test run — no more pasting expiring credentials.
## What Auto-Auth Does
Backend APIs almost always sit behind some form of token-based auth — an OAuth `Bearer`, an AWS Cognito access token, a custom session cookie. Tokens expire. When they do, every test in the run fails until someone pastes a fresh value into the credentials form.
**Auto-Auth removes the manual rotation.** You configure your project's login flow once. Before every test run TestSprite obtains a fresh token and uses it across every backend test in the run.
**One config per project, not per API.** A single configured login flow covers every backend test in the project. There is no per-endpoint auth configuration to manage.
## When to Use This
* Your API uses **bearer tokens, session cookies, or OAuth refresh flows** that expire on a schedule (most modern APIs)
* You're tired of pasting credentials before every scheduled run, or your nightly schedule keeps breaking on Monday morning because Friday's token expired
* You want **scheduled reruns** to run cleanly without human attendance
If your API has no auth, or auth is a static long-lived API key (think Stripe `sk_live_…`), you don't need Auto-Auth — Static Credentials cover that case fine. See [Static Credentials](#if-you-cant-use-auto-auth-static-credentials) at the bottom.
## Prerequisites
* A **Starter** or **Standard** subscription (Auto-Auth is a Pro feature). Free-plan projects see a paywall card with an Upgrade CTA where the configuration would normally appear.
* A backend project with at least one API under test
* Login credentials your API accepts (username/password, OAuth client credentials + refresh token, or AWS Cognito refresh token)
Plan tiers, what each unlocks, and how to upgrade
## Quick Start
From your project's left sidebar, click **Authentication**. The Auto-refresh login card sits at the top of the page.
Opens the configuration modal. Pick your login method — AWS Cognito, OAuth Refresh, or Username / Password.
The form changes based on the method you chose. Click **Test Login** to verify your config works *before* you save — the result panel below the buttons shows the masked token (or a structured error) so you can fix the config without going through a full test run.
Saving runs one final verification. If it succeeds, the card flips its toggle on and shows a green **Verified · Xm ago** badge — your next test run will use a fresh token. If verification fails, the config persists with the toggle off plus a clear error so you can fix and retry.
***
## Choosing a Method
The configuration modal offers three methods. Pick the one that matches your API.
| Method | When to use | What you provide |
| :------------------------- | :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| **AWS Cognito** | Your app uses AWS Cognito user pools (Amplify SDK, common for AWS-hosted apps) | Region, App client ID, Refresh token |
| **OAuth Refresh** *(Beta)* | Standard OAuth 2.0 refresh-token grant — Google, Auth0, Okta, custom OAuth servers | Token endpoint, Client ID, Client secret, Refresh token, optional scope, path to access token |
| **Username / Password** | Your API has a `/login` (or similar) endpoint that takes a username + password and returns a token | Login URL, HTTP method, Content-Type, request body template, username, password, path to access token |
**Not sure which to pick?** AWS Cognito and OAuth Refresh are the recommended starting points if your provider supports them. Username/Password is the simplest mental model but requires your API to expose a password-grant style endpoint, which is less common in modern apps.
***
## AWS Cognito
### What it does
TestSprite uses your stored Cognito refresh token to obtain a fresh access token before each test run. The access token is then attached to your test requests.
### Fields
| Field | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------- |
| AWS Region | The AWS region your Cognito user pool lives in. Defaults to `us-east-1`. |
| App Client ID | The Cognito App client ID (under your User Pool → App integration → App clients). |
| Refresh Token | A long-lived refresh token issued by Cognito for a real user. See "How to obtain a refresh token" below. |
### How to obtain a refresh token
A refresh token is issued when a user successfully signs in. The simplest way to capture one for testing:
Sign in as the test user account you want TestSprite to use.
Cognito Amplify stores the tokens under keys like `CognitoIdentityServiceProvider...refreshToken`. The value is the refresh token string.
Paste it into the Refresh Token field and Test Login.
**Token capture varies by app.** Some apps store tokens in cookies or in-memory only. If you're not sure, ask your auth team for a fresh refresh token issued for a test account — the format is a long opaque string.
### 30-day expiry warning
AWS Cognito refresh tokens are capped at **30 days from issue** by default (this can be configured per app client in AWS, but 30 is the AWS default). When your stored refresh token gets close to expiry, the Authentication tab surfaces a yellow warning badge:
| When you see it | What it means |
| :-------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| **Refresh token expires in 7d** (and counting down) | You have ≤ 7 days before the token will stop working. Capture a fresh one and update the field. |
| **Refresh token expired** | The token is past 30 days. Auto-Auth runs will fail until you update it. |
**OAuth refresh tokens generally don't hard-cap.** The 30-day warning fires only for AWS Cognito. Google / Auth0 / Okta refresh tokens typically last until revoked, so we skip the warning to avoid false alarms.
***
## OAuth Refresh (Beta)
### What it does
TestSprite uses your OAuth provider's standard refresh-token grant to obtain a fresh access token before each test run, and reads the access token out of your provider's response.
### Fields
| Field | Description |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Token Endpoint | The provider's token URL — e.g. `https://oauth2.googleapis.com/token`, `https://your-tenant.auth0.com/oauth/token`. |
| Client ID | Your OAuth app's client ID. |
| Client Secret | Your OAuth app's client secret. Stored encrypted; never echoed back to the browser. |
| Refresh Token | A refresh token issued for the test user. Stored encrypted; never echoed back to the browser. |
| Scope (Optional) | Space-delimited scopes to request, if your provider needs them — e.g. `openid email`. Usually omit unless Test Login fails with a scope-related error. |
| Token Path | Path to the access token in the response body. Default `$.access_token` works for almost all providers. Override only if your provider returns a non-standard shape. |
### Where to get a refresh token
Each provider's flow is different. The most common path:
1. Register a new "OAuth app" in your provider's console (Google Cloud Console, Auth0 Dashboard, Okta Admin)
2. Set the redirect URI to something local like `http://localhost:1234/callback`
3. Use the provider's playground or a small script to walk through the authorization-code flow once and capture the refresh token
**Auth0 hint**: in the Auth0 Dashboard, create a Machine-to-Machine app authorized for your test API. The M2M app's `client_credentials` grant returns short-lived access tokens directly — Auto-Auth's `OAuth Refresh` method also handles this since the token endpoint, client ID, and client secret are the same fields. Set scope to whatever your API requires.
***
## Username / Password
### What it does
TestSprite calls the login endpoint you specify with your username and password, and reads the token out of the JSON response using the path you provide.
### Fields
| Field | Description |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Login URL | The full URL of your login endpoint — e.g. `https://api.example.com/auth/login`. |
| HTTP Method | `POST` (default) or `PUT`. |
| Content Type | `JSON` (default, sends `application/json`) or `Form-urlencoded` (`application/x-www-form-urlencoded`). |
| Body Template | The request body, with `{{username}}` and `{{password}}` placeholders. The default is `{"email":"{{username}}","password":"{{password}}"}`. Edit if your API expects different field names — for example `{"identifier":"{{username}}","secret":"{{password}}"}`. |
| Username / Email | The username/email of your test user. |
| Password | The password of your test user. Stored encrypted; never echoed back to the browser. |
| Token Path | Path to the token in the response — `$.access_token`, `$.token`, `$.data.jwt`, etc. Default `$.access_token`. |
### Body template tips
`{{username}}` and `{{password}}` are placeholders that get filled in with your stored credentials. You can shape the body however your API needs:
```json Standard JSON theme={null}
{ "email": "{{username}}", "password": "{{password}}" }
```
```json Different field names theme={null}
{ "identifier": "{{username}}", "secret": "{{password}}" }
```
```json Extra fields expandable theme={null}
{
"username": "{{username}}",
"password": "{{password}}",
"tenant": "test-org",
"scope": "api"
}
```
```text Form-urlencoded theme={null}
username={{username}}&password={{password}}&grant_type=password
```
**Form-encoded requires Content Type to match**: switch the **Content Type** picker to `Form-urlencoded` if your body uses `key=value` form. The default JSON content type with a form-encoded body fails on most servers with a 400.
***
## Token Injection
Once TestSprite has the token, it has to attach it to your test requests in the right way. The **Inject As** field at the bottom of the modal controls this.
| Inject As | Where the token goes | When to use |
| :---------------------------- | :------------------------------------- | :-------------------------------------------------------------------- |
| Bearer *(default)* | `Authorization: Bearer ` header | Standard for OAuth, Cognito, JWT-based APIs (>90% of cases) |
| Custom Header | `: ` | Your API expects a custom header — e.g. `X-Auth-Token`, `X-API-Key` |
| Cookie | `Cookie: =` | Session-cookie based APIs that don't read tokens from `Authorization` |
When you pick **Custom Header** or **Cookie**, a second field appears asking for the header name (e.g. `X-Auth-Token`) or cookie name (e.g. `session`).
**If unsure, start with Bearer.** Switch to Custom Header / Cookie only if Test Login succeeds (token retrieval works) but actual test runs fail with 401s — that's the signal your token is being delivered to the wrong place.
***
## Test Login: Verify Before You Rely
The **Test Login** button at the bottom of the modal runs a single end-to-end refresh against your config and shows you exactly what came back.
The result panel reports one of:
| State | What it means | What to do |
| :-------------------------------- | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| Success + masked token | Your config retrieved a valid-looking token from the provider | Click **Save** — the same call will run before every test run from now on |
| Failure: auth | The provider rejected your credentials (401/403) | Wrong refresh token, wrong client secret, expired credential. Update the field and retry |
| Failure: parse | Got a 200 from the provider but the token path didn't find a token in the response | Check the **Token path** field — defaults work for most providers, but if yours returns `{"data":{"jwt":"…"}}` you'd need `$.data.jwt` |
| Failure: network | Couldn't reach the provider URL | Wrong endpoint URL, DNS issue, or your endpoint is behind a network not reachable from TestSprite's egress |
**Test Login uses the in-progress values from the form**, not whatever was previously saved. The card outside still shows the previously-saved state until you click **Save**.
***
## Health States on the Authentication Tab
Once configured, the Auto-refresh card shows one of five states. Knowing what each means saves debugging time. The card always shows a green **Pro · Unlocked** badge on Pro plans; the state badge sits next to it.
Auto-Auth is on and the most recent refresh — either Test Login or a real test run — succeeded. **Healthy state.** A fresh token will be fetched before your next test run.
Auto-Auth is on but no successful refresh has happened yet (you turned it on without running Test Login). The first refresh will fire before your next test run. **Suggest running Test Login** so you find out it works without losing a real run.
Auto-Auth is on but the most recent refresh attempt errored. **Tests in this project will be blocked until you fix it** — better to fail fast than to silently run with an expired token. Click **Edit** to see the last error, fix the field that's wrong (often an expired refresh token), Test Login, then Save.
A working config is saved but the toggle is off. Tests will run *without* the auto-refreshed token (they'll fall back to whatever Static Credentials you have). Flip the toggle to re-enable — we run a verification check before flipping the switch on.
No config saved yet. Click **Configure** to start.
***
## Day-2 Operations
### Edit a saved config
Click **Edit** on the card. The modal opens with all non-secret fields pre-populated. Secret fields (password, client secret, refresh token) show `••••••••` as a placeholder and are **preserved if you leave them blank**. Type a new value to overwrite.
**Secrets are never echoed back to the browser.** Leaving the field blank is the "keep what's stored" gesture.
### Temporarily disable
Flip the toggle on the card off. The config stays saved; new test runs skip Auto-Auth and fall back to your Static Credentials (if any). Flip back on — TestSprite verifies the config still works before re-enabling.
### Delete a config
Use **Edit** → clear all fields → **Save**. Or contact support if you want a hard delete.
***
## Security
* **Encrypted at rest**: secrets (password, client secret, refresh token) are stored encrypted.
* **Never echoed back to the browser**: saved secrets render as `••••••••` placeholders in the form. Leaving the field blank keeps the stored value.
* **Server-side only**: Test Login and the actual token refresh both run on the server. Your secrets never traverse the browser-to-API path.
* **No credential logging**: full request bodies are not logged.
***
## If You Can't Use Auto-Auth: Static Credentials
If Auto-Auth's three methods don't fit your API — for example, you have a long-lived API key that never expires, or your auth flow requires a hardware token, or you're on the Free plan and don't want to upgrade — you can still run backend tests by **pasting credentials manually**.
The **Authentication** tab on your project shows, in addition to the Auto-Auth card, a per-API-family credentials section where you can:
* Paste a token, API key, or session string per API family (Users, Orders, Payments, etc.)
* Apply the same value to multiple APIs sharing an auth type via the **All `` · N APIs** bulk-update buttons (e.g. "All Bearer · 3 APIs")
* Rotate (overwrite) without removing the test cases that use them
The catch: **you have to paste a fresh value when the token expires**. For test schedules that run nightly with short-lived tokens, this becomes a daily chore — which is exactly the pain Auto-Auth removes.
| | Static Credentials | Auto-Auth |
| :----------------------- | :----------------------- | :---------------------------------- |
| Plan | Free + paid | Paid only |
| Setup effort | Paste & save | Configure once + Test Login |
| Token expiry | You re-paste manually | Refreshed automatically |
| Works for scheduled runs | Only until token expires | Yes — every run gets a fresh token |
| Multi-API setup | Per-family credentials | One config covers the whole project |
***
## Troubleshooting
Three usual culprits, in order of likelihood:
1. **Refresh token has expired or been revoked.** AWS Cognito caps at 30 days; OAuth providers revoke on password change, app uninstall, or admin action. Capture a fresh refresh token and update the field.
2. **Client ID / client secret mismatch.** Double-check you copied them from the right OAuth app — different environments (dev/prod) have different client IDs.
3. **Account is disabled or locked.** Try signing in to your app with the test user's credentials in a browser; if the manual sign-in fails, fix that first.
The provider returned a 200 but the **Token path** didn't find a token in the response.
* Default `$.access_token` works for AWS Cognito, Auth0, Okta, Google, most standards-compliant providers
* If your response shape is `{"data":{"jwt":"…"}}`, set token path to `$.data.jwt`
* If your response shape is `{"token":"…"}`, set token path to `$.token`
* Use the failing response body in the error toast as your reference
Token retrieval works but the token isn't being delivered to your API in the way it expects.
* Check the **Inject As** picker: try **Bearer** first; if that fails, try **Custom Header** with the header name your API documentation specifies (e.g. `X-Auth-Token`); if that fails, try **Cookie**
* For Cookie injection, the cookie name field expects just the name (e.g. `session`), not `Cookie: session=…`
Save-time verification flipped your toggle back to off because the verification refresh failed. Open **Edit**, read the error surfaced below the dialog title, fix the underlying issue, Test Login to confirm, then Save again.
Auto-Auth handles those independently — the **Inject As** field controls how the *fetched* token is attached to your test requests, while the login endpoint's Content-Type is the **Content Type** field in the Username/Password method (or implicit for OAuth/Cognito). They don't conflict.
For Username/Password method: the password rotation breaks Auto-Auth until you update the password field. For OAuth/Cognito: refresh tokens generally survive password rotation (until explicitly revoked) — switching to OAuth Refresh or Cognito eliminates this churn.
***
## Where to Go Next
How TestSprite finds your endpoints from PRD + code
Multi-step chained tests with dynamic variables
Re-run a chain or just the failed step
See what each tier unlocks