---
title: Authentication | TestingBot MCP
description: Authenticate the TestingBot MCP server with browser login (tb_login),
  the device-code flow, or an API key and secret. Credentials, env vars and security.
source_url:
  html: https://testingbot.com/support/ai/mcp/authentication
  md: https://testingbot.com/support/ai/mcp/authentication/index.md
---
# Authentication

Before the TestingBot MCP server can manage tests, drive real browsers or query your account, it needs your TestingBot credentials. There are three ways to authenticate, and the right one depends on where you run your MCP client, a desktop machine, an SSH session, a CI pipeline or a hosted web client.

This page covers all three methods, where credentials are stored, the full list of environment variables you can set, and how the server behaves when no credentials are present. If you have not installed the server yet, start with [Setup & installation](https://testingbot.com/support/ai/mcp/setup) first.

## Authentication methods

The TestingBot MCP server supports three authentication methods:

- **Browser login** , run the `tb_login` tool and authorize in a browser window on your local machine. No keys are ever pasted into your AI client. This is the recommended option for desktop use. 
- **Device-code flow** , a variant of `tb_login` for SSH, remote, headless or hosted web clients. You get a short code, open [https://testingbot.com/device](https://testingbot.com/device) on any device and authorize there. 
- **API key & secret** , set `TESTINGBOT_KEY` and `TESTINGBOT_SECRET` in your client's `env` block. Best for CI and shared, non-interactive configurations. 

### Configuration precedence

When the server starts it resolves credentials in this fixed order:

1. **Environment variables** , if _both_ the key (`TESTINGBOT_KEY`) _and_ the secret (`TESTINGBOT_SECRET`) are set, they are used. 
2. **Credentials file** , otherwise the server reads `~/.testingbot/credentials` (written by `tb_login`). 
3. **Degraded mode** , if neither is available, every tool except `tb_login` replies that no credentials are configured. See [Degraded mode](https://testingbot.com#degraded) below. 

Environment variables always win. If you set a key and secret in your client's `env` block, the server uses those and never touches the credentials file, so you do not need to run `tb_login`.

## Browser login with tb\_login (loopback)

The simplest way to authenticate on a desktop is the `tb_login` tool. It uses a loopback authorization flow (RFC 8252): the server opens your default browser to TestingBot, you click **Authorize** while signed in, and the credentials are captured on a local `127.0.0.1` callback. Nothing is ever copied, pasted or shown to your AI client.

### How it works, step by step

1. Ask your AI client to authenticate, for example:

> "Log in to TestingBot"

1. Your client invokes the `tb_login` tool.
2. The server opens your default browser to TestingBot and starts a temporary local callback listener.
3. If you are not signed in yet, log in to your TestingBot account, then click **Authorize**.
4. The browser redirects back to the local `127.0.0.1` callback and the credentials are captured.
5. The server writes them to `~/.testingbot/credentials` and starts using them immediately, no restart needed.

After this, all other tools (such as `getUserInfo`, `getTests` or `tb_openBrowser`) work automatically because the server reads the credentials file.

Loopback login is the default on a desktop machine. You do not need to specify a `mode`, `auto` picks loopback when a browser is available. See [The mode parameter](https://testingbot.com#mode).

Loopback login needs a local browser and the ability to open a `127.0.0.1` listener. On an SSH session, a container, a CI runner or a hosted web client there is no local browser to open, use the [device-code flow](https://testingbot.com#device-code) instead.

## Device-code flow

When there is no local browser (SSH sessions, remote or headless hosts, containers, or web-based MCP clients), use the device-code flow (RFC 8628). Instead of opening a browser locally, the server prints a short code that you enter on any device with a browser.

### How it works, step by step

1. Run `tb_login` with the device mode, for example: 

> "Log in to TestingBot using the device code flow"

1. The server prints a short, human-readable code.
2. On any device, open [https://testingbot.com/device](https://testingbot.com/device).
3. Enter the code, sign in if needed, and click **Authorize**.
4. The server detects the approval, writes the credentials to `~/.testingbot/credentials` and starts using them.

The device flow is **resumable**. If the polling window closes before you finish authorizing, just run `tb_login` again and the server will continue where it left off. You can tune the polling and lifetime windows with the [device/loopback environment variables](https://testingbot.com#env-vars).

## The mode parameter

`tb_login` takes a single optional `mode` parameter that chooses the authorization flow. You can also set a default with the `TESTINGBOT_AUTH_MODE` environment variable.

| Value | Best for | Behavior |
| --- | --- | --- |
| `auto` | Most users (default) | Picks `loopback` on a desktop and falls back to `device` on a headless host. |
| `loopback` | Desktop machines | Opens the browser to TestingBot; you click Authorize; credentials are captured on a local `127.0.0.1` callback. Nothing pasted. |
| `device` | SSH / remote / headless / web clients | Prints a short code; open [https://testingbot.com/device](https://testingbot.com/device), enter it and Authorize. Resumable. |

For example, to force the device flow regardless of environment, ask your client to run `tb_login` with `mode` set to `device`, or set `TESTINGBOT_AUTH_MODE=device` in your client's `env` block.

## API key & secret

As an alternative to `tb_login`, you can supply your TestingBot API key and secret directly. This is the preferred option for CI pipelines and shared configurations where there is no interactive browser. Add them to your MCP client's `env` block:

    {
      "mcpServers": {
        "testingbot": {
          "command": "npx",
          "args": ["-y", "@testingbot/mcp-server@latest"],
          "env": { "TESTINGBOT_KEY": "<key>", "TESTINGBOT_SECRET": "<secret>" }
        }
      }
    }

You can find your key and secret on your [TestingBot account page](https://testingbot.com/members/user/edit). Both must be set for the environment-variable path to take effect.

Prefer `tb_login` for day-to-day local use, it keeps your key and secret out of config files entirely. Reach for the `env` block when you need a non-interactive setup such as CI. See [Setup & installation](https://testingbot.com/support/ai/mcp/setup) for the full per-client configuration.

Treat your API secret like a password. Avoid committing config files that contain it to version control; use your CI provider's secret store and reference the values as environment variables instead.

## Where credentials live

When you authenticate with `tb_login`, the server stores your credentials in an INI file at `~/.testingbot/credentials`. The file is organized into profile sections so you can keep more than one account on the same machine:

    [default]
    key = your-api-key
    secret = your-api-secret

By default the server reads the `[default]` profile. To use a different profile, set `TESTINGBOT_PROFILE`; to relocate the whole directory, set `TESTINGBOT_CONFIG_DIR`.

### File permissions

The credentials are written with restrictive permissions so other users on the machine cannot read them:

- The directory `~/.testingbot` is created with mode `0700` (owner only).
- The `credentials` file is written with mode `0600` (owner read/write only).

Credentials supplied through environment variables are never written to the credentials file. If you ever want to start fresh, delete `~/.testingbot/credentials` and run `tb_login` again.

## Environment variables

The following environment variables can be set in your MCP client's `env` block (or your shell) to control authentication and connection behavior. Several have aliases for compatibility with existing TestingBot tooling.

| Variable | Aliases | Default | Description |
| --- | --- | --- | --- |
| `TESTINGBOT_KEY` | `TB_KEY`, `TESTINGBOT_USERNAME` | – | Your TestingBot API key. |
| `TESTINGBOT_SECRET` | `TB_SECRET`, `TESTINGBOT_ACCESS_KEY` | – | Your TestingBot API secret. Both key and secret must be set for the env path to apply. |
| `TESTINGBOT_AUTH_MODE` | – | `auto` | Default `tb_login` mode: `auto`, `loopback` or `device`. |
| `TESTINGBOT_BASE_URL` | – | `https://testingbot.com` | Override the TestingBot API endpoint. |
| `TESTINGBOT_CONFIG_DIR` | – | `~/.testingbot` | Override the directory that holds the credentials file. |
| `TESTINGBOT_PROFILE` | – | `default` | Credentials profile (section) name to read from the credentials file. |
| `WDIO_LOG_LEVEL` | – | `silent` | WebDriver client log level. The server sets it to `silent` by default; rarely changed. |
| `TESTINGBOT_DEVICE_POLL_WINDOW_MS` | – | `25000` | Device-code polling window, in milliseconds. |
| `TESTINGBOT_LOOPBACK_WAIT_MS` | – | `60000` | How long the loopback flow waits for you to authorize, in milliseconds. |
| `TESTINGBOT_LOOPBACK_LIFETIME_MS` | – | `900000` | Maximum lifetime of the loopback authorization session, in milliseconds. |

## Degraded mode

If the server cannot find credentials (neither a key/secret pair in the environment nor a credentials file), it starts in **degraded mode**. In this state every tool except `tb_login` returns a message like:

    No TestingBot credentials configured. Run the tb_login tool to authenticate.

This is not an error in your client configuration, it simply means you have not authenticated yet. To fix it:

- Run the `tb_login` tool (ask your client to "log in to TestingBot"), or
- Set `TESTINGBOT_KEY` and `TESTINGBOT_SECRET` in your client's `env` block and reload the server.

Seeing the "Run tb\_login" message repeatedly after authenticating? Check the [Troubleshooting](https://testingbot.com/support/ai/mcp/troubleshooting) page, it is usually a profile or config-directory mismatch.

## Security notes

The TestingBot MCP server is designed so your credentials stay under your control and never leak into your AI conversation.

- **Credentials stay local.** Whether captured by `tb_login` or read from environment variables, they live on your machine (in `~/.testingbot/credentials` or the process environment) and are never sent to your LLM provider. 
- **Direct API calls.** The MCP server talks directly to the TestingBot API. Your AI client sends natural-language requests to the local server; the server performs the work and returns results. 
- **No key pasting.** The browser and device-code flows capture credentials out of band, so your key and secret never pass through the chat transcript. 
- **Restrictive permissions.** The credentials file is written `0600` inside a `0700` directory, readable only by your user account. 

Next steps: review the [Tool reference](https://testingbot.com/support/ai/mcp/tools) to see what you can do once authenticated, browse common [use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases), or return to the [TestingBot MCP overview](https://testingbot.com/support/ai/mcp).

### Looking for more help?

Have questions or need more information? Reach out via email or Slack.

[Email us](https://testingbot.com/contact/new)[Slack Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)