Projects

Project Auth

Routebase configures API authentication per environment: each environment of a project carries its own auth scheme and credentials, and test runs inherit it automatically. Configure Basic Auth once on Staging and OAuth 2.0 on Production, and the same test suite authenticates correctly against both.

Where auth is configured

  • Environment detail sheet → Auth tab — open an environment from the Projects page sidebar and switch to Auth. This is where you set, test, copy, and clear the configuration. The tab notes: "Authentication for this environment. Test suites inherit this unless overridden."
  • Project Settings → Authentication by Environment — a read-only overview table listing every environment with its auth type badge and when it was last updated, so you can spot unconfigured environments at a glance.
The Auth tab of an environment with an OAuth 2.0 configuration

Supported auth types

The Auth Type selector offers:

Group Type What it does
Common None No authentication headers.
Common Basic Auth Sends username and password encoded with Base64 in the Authorization header.
Common Bearer Token Sends a token in the Authorization header as Bearer <token>.
Common API Key Sends an API key as a custom header or query parameter — you choose the key name and whether it goes in Header or Query.
OAuth OAuth 2.0 Obtains and manages access tokens; supports Client Credentials, Authorization Code, and Auth Code + PKCE grants.
OAuth OAuth 1.0 Signature-based authentication for legacy APIs.
Token JWT Bearer Generates a signed JSON Web Token from a secret or private key, with a live preview of the token payload.
Other Digest Auth HTTP Digest challenge-response authentication.
Other AWS Signature V4 Signs requests for AWS services.
Other Hawk Auth HMAC-based authentication with timestamp and nonce.
Other NTLM Auth Windows NT LAN Manager challenge-response authentication.

Every credential field accepts {{VARIABLE_NAME}} placeholders with autocomplete from the environment's resolved variables — keep the scheme in the auth config and the secrets in secret variables. Changes save automatically as you type.

OAuth 2.0 tokens

For OAuth 2.0 configurations, a token manager below the form lists stored tokens with their grant type and expiry, and lets you request a new token, refresh, copy, or delete existing ones — per environment.

Testing an auth configuration

The Quick Test section sends a probe request with the configured credentials: pick an HTTP method, enter a test URL, and Routebase reports the status code, response time, and any error — so you can validate credentials before a whole suite depends on them.

Copying auth between environments

Click Copy to... on the Auth tab and pick a target environment. The configuration is copied with its secret fields masked, and OAuth 2.0 tokens never travel — the target fetches its own.

One case is refused outright rather than copied incomplete: if the source auth holds a literal secret — a credential typed straight into the field — the copy is rejected with "The source environment stores a literal secret. Configure authentication manually in the target environment." Auth built from {{VARIABLE}} references copies without complaint, because each environment then resolves its own value. That is the practical argument for referencing variables rather than pasting credentials: it is what makes an auth setup portable.

Clear Auth removes the configuration from an environment entirely.

How auth is inherited

Requests resolve their effective auth along a chain, most specific first:

  1. Suite-level auth (if set) — each test suite has an Authentication setting in its configuration sheet with three modes:
    • Inherit from Environment (default) — uses the active environment's auth. A badge shows what is inherited, e.g. Inherited: Bearer (Environment), and a warning appears with a Configure Auth shortcut if the environment has no auth configured.
    • Custom Auth — a suite-specific configuration using the same form and auth types as environments.
    • No Auth — no authentication headers for this suite, regardless of the environment.
  2. Environment-level auth — the per-environment configuration described above.

Inheritance badges are color-coded throughout the testing UI: blue for inherited, orange for custom, gray for none.

A test suite's Authentication setting showing the Inherit from Environment mode with inheritance badge

Monitors do not use the environment auth configuration — give a monitor explicit request headers instead, using {{variable}} placeholders for credentials (see Monitors). Security scans authenticate through personas, which carry their own credential configuration (see Personas).

Permissions

Configuring environment and suite auth requires the tests:write permission, which all roles (Member, Admin, Owner) have by default. Secret credential values follow the same encryption and masking rules as secret variables.

  • Environments — where auth configurations live
  • Variables — keep credentials in secret variables
  • Test Suites — suite-level auth modes and inheritance
  • Personas — credentials for security scanning
  • Monitors — header-based auth for uptime checks