# Setting Up API Authentication in Routebase, End to End — Routebase > Configure credentials once per environment, inherit them everywhere, keep secrets in variables, and cover the pipeline, scans and agents from one setup. Canonical page: https://routebase.dev/guides/api-authentication/setting-up-authentication-in-routebase/ Chapter 9 of 11 · API Authentication · Last reviewed 2026-09-12 · The Routebase Team This chapter is the how-to, and it assumes you have picked a method already. The chapters before it cover the methods, and what follows is the configuration path from an empty project to a suite, a pipeline, a security scan and an agent all authenticating correctly. ## The shape of it Authentication in Routebase lives at the environment level, and everything else either inherits it or overrides it deliberately. | Surface | Where its credentials come from | |---|---| | Test suites and cases | The active environment, unless the suite or case overrides | | The API Designer's Try It | The selected environment | | Monitors | Their linked environment, applied to every check | | Security scans | Personas, which carry their own credentials | | The CLI and CI | The environment named in the command, with an optional per-run override | | An AI agent over MCP | Its own API key, separate from anything your API uses | Two of those need flagging early because they surprise people. Monitors do use the linked environment's authentication, and security scans do not, because a scan needs several identities and takes them from personas instead. ## Step 1, put the secret in a variable Do this before configuring authentication, because it changes what the rest looks like. Open the environment, go to its **Variables** tab, and create a secret variable for each credential value. A client secret, an API key, a password, a signing key, all of them belong here and not in the auth form. The payoff arrives immediately and it compounds later. Secret variables are encrypted and masked, and an auth configuration built from references is portable between environments, while one holding a literal secret is not. ## Step 2, configure the environment's auth Open the environment's **Auth** tab, which notes that test suites inherit this unless overridden, and pick the scheme. ```txt Auth Type OAuth 2.0 Grant type Client Credentials Token URL https://auth.example.com/oauth/token Client ID {{OAUTH_CLIENT_ID}} Client secret {{OAUTH_CLIENT_SECRET}} Scope orders.read orders.write Client auth Basic header ``` Every credential field takes a `{{VARIABLE}}` placeholder with autocomplete from the environment's resolved variables, and changes save as you type. For OAuth 2.0 a token manager appears below the form. It lists the stored tokens with their grant type and expiry, and it requests, refreshes, copies or deletes one. Tokens belong to that one environment and are never shared with another. ## Step 3, prove the credentials work Expand **Test Authentication** below the form, pick a method, enter a test URL and run the probe. Routebase reports the status code, the status text and the response time. Do this before a suite depends on the configuration. A wrong client secret found here takes a minute, and the same wrong secret found through a suite of forty red cases takes considerably longer to diagnose. ## Step 4, repeat for each environment, or copy Every environment carries its own credentials, so staging and production have separate configurations by design. **Copy to** on the Auth tab copies a configuration to another environment. Secrets are masked in transit, OAuth tokens never travel because the target fetches its own, and one case is refused outright. A source holding a literal secret cannot be copied, and the message says to configure the target manually. That refusal is the reason step one comes first. A configuration built from `{{VARIABLE}}` references copies without complaint, because each environment resolves its own values. ## Step 5, let suites inherit, and override where needed A suite's **Authentication** setting in its configuration sheet has three modes. _Figure: Authentication resolves from the outside in, so a suite and its cases inherit the environment until one of them overrides it._ _Screenshot: A suite inherits the environment's authentication until you override it, and the badge names what it resolved to._ | Mode | Behaviour | |---|---| | **Inherit from Environment** | The default, using whatever the active environment defines. A badge shows what was inherited | | **Custom Auth** | A suite-specific configuration using the same form and the same catalogue | | **No Auth** | No authentication headers for this suite, whatever the environment says | Inheritance badges are colour-coded across the testing surface, where blue means inherited, orange means custom and grey means none. A warning with a shortcut appears when a suite inherits from an environment that has no authentication configured. **No Auth** is not an edge case, and it is how the negative tests in [testing authentication](/guides/api-authentication/api-authentication-testing/) send no credential on purpose. ## Step 6, the pipeline A CI run authenticates twice, and separating the two saves confusion. **The run itself** authenticates with a Routebase API key, created under Settings, scoped to the permission the command needs and restricted to one project. Store it as a pipeline secret. **The requests the tests send** authenticate with whatever the named environment defines, exactly as they do in the browser. Where the pipeline holds a fresher credential, such as a token minted for this build, override it for that run instead of storing it. The override accepts bearer, basic and API key forms, applies to that run only, and is never persisted. ## Step 7, personas for security scans Security scanning uses **personas** instead of environment authentication, because the authorization scanners need more than one identity to compare. A persona is a named set of credentials using the same auth editor as everywhere else, and it must carry a real scheme, since none is rejected. Persona secrets are encrypted and never returned to the browser, so editing a persona's name leaves the stored credentials untouched, and changing the credentials means re-entering the configuration in full. **Test** on a persona card sends a probe to a chosen environment and reports whether the credentials reached the target. A 2xx, a 401 and a 403 all count as reached, because the question is whether they travelled and not whether they were accepted. For object-level checks, use personas that belong to different tenants entirely. For function-level and property-level checks, use personas with a clear privilege gap. ## Step 8, the specification Documenting the scheme in the specification is a separate act from configuring credentials, and it is what tells consumers, generated clients and agents how to authenticate. Create a security scheme component of the right type, then attach it to endpoints, using the bulk assignment across all endpoints, a folder, a tag or a selection. See [designing authentication into your specification](/guides/api-authentication/openapi-security-schemes/). ## Step 9, agents over MCP An agent authenticates to Routebase with its own API key or an OAuth sign-in, and that credential is entirely separate from anything your API uses. Give it explicit scopes and restrict it to one project. Scopes are enforced twice, because tool discovery only advertises what the credential allows and every call is checked again server-side. Secret variables are write-only over MCP, since every read masks the value, so an agent can set a credential and never read one back. ## A checklist - [ ] Every credential value is a secret variable, and no auth field holds a literal - [ ] Each environment has its own configuration, verified with Test Authentication - [ ] Suites inherit by default, and every override exists for a stated reason - [ ] At least one suite or case sends no credential, to cover the 401 path - [ ] The pipeline key is scoped to one project and one permission set - [ ] Personas exist for the authorization scanners, from different tenants - [ ] The specification documents the scheme, assigned to every endpoint that needs it ## Related product documentation [Project Auth](https://docs.routebase.dev/project-auth/) for the editor and inheritance, [Environments](https://docs.routebase.dev/environments/) for where configurations live, [Variables](https://docs.routebase.dev/variables/) for secrets, [Test Suites](https://docs.routebase.dev/test-suites/) for suite-level modes, [Personas](https://docs.routebase.dev/personas/) for scan identities, [CLI in CI/CD](https://docs.routebase.dev/cli-in-cicd/) for the pipeline and [MCP Authentication](https://docs.routebase.dev/mcp-authentication/) for agents. ## Frequently asked questions ### Where is authentication configured in Routebase? On the environment, under its Auth tab, so each environment of a project carries its own scheme and credentials. Test suites inherit that configuration by default, and a suite or an individual case overrides it when it needs a different identity. Security personas and the specification's security schemes are separate surfaces that use the same editor. ### How do you keep API credentials out of test configuration? Store the value as a secret variable on the environment and reference it from the credential field as a variable placeholder. The configuration then holds a reference instead of a value, so nothing sensitive appears in an export, a copy to another environment or a screenshot. Routebase refuses to copy an auth configuration that holds a literal secret, and that is what makes the referenced form the easy one. ### Can a test suite use different credentials from its environment? Yes. Suite authentication has three modes. It inherits from the environment, uses a custom configuration of its own, or sends no authentication at all. The third mode is what makes a negative test possible, since proving that an endpoint returns 401 requires a way to send no credential. ### How does a CI pipeline authenticate a Routebase test run? With an API key stored as a pipeline secret, scoped to the permission the command needs and restricted to one project. The key authenticates the run itself, while the credentials the tests send to your API come from the environment as usual. A pipeline holding a fresher credential can also override the auth for one run without persisting it anywhere. --- [Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.