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

# Security & Access

> This page is for IT and security reviewers. It covers what network access Checksum needs, what it can read and write in your repositories, which credentials it holds, and how each connection is scoped and revoked.

## At a glance

| Area | Summary |
| - | - |
| Inbound to your app | Checksum's agents and test runners reach your test environment from fixed IP addresses you can allowlist |
| Outbound from your network | CLI, CI, API, and MCP clients call `api.checksum.ai` over HTTPS (443) |
| Code repository | **Read-only.** Checksum never writes to it. |
| Tests repository | Read + write. Checksum delivers every change as a pull request for you to review. |
| Test credentials | Stored securely and used only during test execution |
| Your local machine | Code is never uploaded from it. Checksum clones from your Git provider in the cloud. |
| User sign-in | Microsoft Entra ID SSO with minimal delegated scopes (`openid`, `email`, `User.Read`) |

<div className="ai-ref">
  <Accordion title="Reference for AI: security at a glance" icon="robot">
    #### Checksum endpoints to allow from your network

    | Host / URL | Port | Used by |
    | - | - | - |
    | `api.checksum.ai` | 443 (HTTPS) | Checksum CLI (`npx checksumai`) |
    | `https://api.checksum.ai/public-api/v1/`, `https://api.checksum.ai/public-api/v2/` | 443 (HTTPS) | CI jobs and scripts calling the REST API |
    | `https://api.checksum.ai/public-api/mcp` | 443 (HTTPS) | MCP clients (Claude Code, Cursor, VS Code…) |
    | `https://app.checksum.ai` | 443 (HTTPS) | Browsers using the web app |

    * Code repository: read-only. Tests repository: read + write; every change arrives as a pull request.
    * API key: one per project, sent as `Authorization: Bearer $CHECKSUM_API_KEY`. Store it only in CI secrets or a secret manager.
    * MCP browser sign-in: scoped to the projects the user approves, re-checked on every request.
    * Inbound: Checksum reaches the test environment from fixed IP addresses. The list is provided by the Checksum contact during onboarding, or on request from `support@checksum.ai`.
  </Accordion>
</div>

<div className="part dev"><span className="part-icon">{"</>"}</span><div><div className="part-title">Developer guide</div><div className="part-sub">Network, repository scopes, credentials, API keys, and MCP tokens</div></div></div>

## Network access

Two directions of traffic are involved: your tools calling Checksum, and Checksum reaching your test environment.

### Let your tools reach Checksum

These run inside your network and call Checksum:

| Client | Destination |
| - | - |
| Checksum CLI (`npx checksumai`): env download, result upload, auto-heal dispatch | `api.checksum.ai` · HTTPS 443 |
| CI jobs and scripts calling the REST API | `https://api.checksum.ai/public-api/v1/` and `/v2/` |
| MCP clients (Claude Code, Cursor, VS Code…) | `https://api.checksum.ai/public-api/mcp` |
| Browsers using the web app | `https://app.checksum.ai` |

If traffic to `api.checksum.ai` hangs or fails on a corporate network, ask IT to allow it over HTTPS (port 443). A TLS-inspecting proxy can break connections by re-signing certificates, so add `api.checksum.ai` to its bypass list. To test:

```bash theme={null}
curl -I https://api.checksum.ai/public-api/mcp
```

### Let Checksum reach your test environment

Checksum's AI agents and Playwright runners must be able to load your UAT/test environment. If it's behind a VPN, firewall, or similar protection, **allowlist Checksum's IP addresses**. Your Checksum contact provides the current list during onboarding. You can also request it from [support@checksum.ai](mailto:support@checksum.ai).

Also make sure bot-protection, WAF, or rate-limiting rules don't block automated Playwright traffic from Checksum's addresses. During onboarding, Checksum checks that the bot isn't blocked and that the AI can reach your site. Fix any access blockers before the POV kickoff date so they don't delay your evaluation. See [Onboarding & Proof of Value](/docs/onboarding).

<Note>
  **Symptom of a blocked environment**

  An [agent session](/docs/agent-sessions) that ends **Failed** because "the application under test was unreachable" is almost always a network or allowlist problem.
</Note>

<div className="ai-ref">
  <Accordion title="Reference for AI: network requirements" icon="robot">
    | Direction | Source → destination | Protocol / port | Notes |
    | - | - | - | - |
    | Outbound | Checksum CLI (`npx checksumai`) → `api.checksum.ai` | HTTPS / 443 | Env download, result upload, auto-heal dispatch |
    | Outbound | CI jobs / scripts → `https://api.checksum.ai/public-api/v1/`, `https://api.checksum.ai/public-api/v2/` | HTTPS / 443 | REST API |
    | Outbound | MCP clients → `https://api.checksum.ai/public-api/mcp` | HTTPS / 443 | Streamable HTTP |
    | Outbound | Browsers → `https://app.checksum.ai` | HTTPS / 443 | Web app |
    | Inbound | Checksum AI agents and Playwright runners → your UAT/test environment | Your app's protocol | Allowlist Checksum's IP addresses (list from your Checksum contact). Bot protection, WAF, and rate limits must not block automated Playwright traffic. |

    * Connectivity test: `curl -I https://api.checksum.ai/public-api/mcp`
    * TLS-inspecting proxies must have `api.checksum.ai` on their bypass list, because certificate re-signing breaks connections.
    * Symptom of a blocked environment: an agent session ends **Failed** with "the application under test was unreachable".
  </Accordion>
</div>

## Repository access

Checksum connects to two kinds of repositories, and each gets a different access level:

| Repository | What Checksum does with it | Access |
| - | - | - |
| **Code repository** (your application) | Reads application code and pull request context so the agents understand the product: routes, components, data flows | **Read-only** |
| **Tests repository** | Writes generated and healed tests, creates branches, opens pull requests, comments, and may auto-merge | Read + write |

On GitHub you install the Checksum GitHub App on the repositories you choose, so you never pick scopes yourself. GitLab, Bitbucket, and Azure DevOps use an access token with read-only scopes for the code repository. For the exact minimum scopes per provider, open [Reference for AI: repository scopes](#repository-access), or see [Git Integration → Permissions](/docs/git-integration#required-permissions).

For tests-repository permissions, protected-branch notes, and connection steps, see [Git Integration → Permissions](/docs/git-integration#required-permissions).

<Tip>
  **You stay in control of what merges**

  Your repository is always the source of truth. By default, every generated or healed test arrives as a PR that you review and merge on your terms. If you turn on auto-merge, Checksum's PRs merge without a human review. See [Test Repository & Config](/docs/test-repository).
</Tip>

<div className="ai-ref">
  <Accordion title="Reference for AI: repository scopes" icon="robot">
    | Provider | Code repository (minimum) | How access is granted |
    | - | - | - |
    | GitHub | `Metadata: Read`, `Contents: Read`, `Pull requests: Read` | Checksum GitHub App, installed on selected repositories. You don't pick scopes. May require an org **owner**. |
    | GitHub Enterprise Cloud (`*.ghe.com`) | Same as GitHub | A Checksum GitHub App registered on your own instance. No tokens or secrets are shared. Requires an org **owner**. |
    | GitLab | `read_api`, `read_repository`, role `Reporter` | Personal or project access token |
    | Bitbucket | `Repositories: Read`, `Pull requests: Read` | Repository access token |
    | Azure DevOps | PAT with `Code (Read)` | Personal access token (code repositories only) |

    * Code repository access is read-only on every provider. Checksum never writes to it.
    * Tests repository access is read + write: it writes generated and healed tests, creates branches, opens pull requests, comments, and may auto-merge. Tests-repository scopes and protected-branch notes: [Git Integration → Permissions](/docs/git-integration#required-permissions).
    * Azure DevOps supports code repositories only.
  </Accordion>
</div>

## Data and credentials

### Test user credentials and variables

* Test users (username/password per environment) and custom environment variables are configured under **Settings → Testing Environment**. They are stored securely and used only during test execution. See [Environments & Test Users](/docs/environments#test-users).
* Your tests repository reads credentials and variables from a local `.env` file that Checksum maintains and you download with `npx checksumai dotenv --download`, so you don't commit secrets to source control. Adding them in the web app doesn't update `.env`. Keep `.env` out of git.
* In CI, pass credentials as CI secrets. Variables set explicitly take precedence over the downloaded `.env`.
* Use dedicated test accounts in a UAT/test environment, not real users' accounts.

### Source code

* Checksum clones your repositories from your connected Git provider **in the cloud**. Code is never uploaded from a developer's machine, including when you use the MCP server, which only carries instructions and results.

### Test artifacts

* When report hosting is enabled (by default when `CI=true`), the CLI uploads results, videos, screenshots, HAR files (network traffic), and Playwright traces to the Checksum dashboard. Local runs keep reports local unless you enable `hostReports`. See [Results, Reports & Traces](/docs/results-and-reports).
* HAR files and traces can capture request and response data from your test environment. Keep that in mind when choosing test data.
* Report and trace links returned through MCP are **signed and expire**.

## API keys

Each project has a **project API key** (**Settings → Project Settings**). The CLI, CI pipelines, the REST API, and API-key MCP connections all use it. See [API Keys & Authentication](/docs/authentication#your-api-key).

<Warning>
  **Treat the key as a secret**

  Anyone with the key can run tests, access your project, start billable cloud runs, and open pull requests on your repo. Store it only in CI secrets or a secret manager, and never in committed files.
</Warning>

* An API key is tied to exactly one project.
* If a key may have leaked, rotate it in **Settings → Project Settings** and update your CI secrets.
* MCP clients that store a key in a config file (Claude Code `--header`, Cursor `mcp.json`) store it in plain text. Prefer browser sign-in, or VS Code's `inputs` prompt.

## MCP connections

* **Browser sign-in is scoped.** At approval time you choose which projects a client may act on. A client can never reach a project you didn't approve.
* **Access is re-checked on every request.** If you lose access to a project, the client loses it too.
* **Connections belong to the user, not the project.** Review or revoke them from the **MCP connections** card on **My Profile**. Revoking cuts the client off from every project you granted.
* **Tools that cost money or open PRs are marked as such**, so clients can ask for confirmation first.

Full details: [MCP server](/docs/coding-agents#mcp-server-connect-and-use).

<div className="ai-ref">
  <Accordion title="Reference for AI: API key and MCP token behavior" icon="robot">
    | Credential | Scope | Where it lives | Revoke / rotate |
    | - | - | - | - |
    | Project API key | Exactly one project. Can run tests, access the project, start billable cloud runs, open PRs. | **Settings → Project Settings**. Sent as `Authorization: Bearer $CHECKSUM_API_KEY`. Store in CI secrets or a secret manager. | Rotate in **Settings → Project Settings**, then update CI secrets |
    | MCP browser sign-in | The projects approved at sign-in, re-checked on every request. Belongs to the user, not the project. | No key stored | **My Profile → MCP connections** (cuts off every granted project) |
    | MCP with API key | One project (the key's) | Plain text in Claude Code config (`--header`) or Cursor `mcp.json`. VS Code `inputs` prompts and stores it securely. | Rotate the API key |
    | Test user credentials | Per environment | **Settings → Testing Environment** for web app features. For your tests, in the `.env` maintained by Checksum and downloaded by `npx checksumai dotenv --download`. Used only during test execution. | Edit in **Settings → Testing Environment**, and ask Checksum to update `.env` |
    | Report / trace links via MCP | A single artifact | Returned by `checksum_test_run_download` | Signed and expire automatically |
  </Accordion>
</div>

<div className="part ui"><span className="part-icon">▦</span><div><div className="part-title">In the Checksum web app</div><div className="part-sub">Roles, admin actions, and revoking access</div></div></div>

## Workspace roles and admin actions

| Action | Who can do it |
| - | - |
| Add, edit, or remove notification connectors | Workspace **admin** |
| Install the `@checksum` Slack bot | Workspace **admin** |
| Install the Checksum GitHub App / GHE app | A GitHub organization **owner** may be required |
| Trigger `/checksum generate` on a PR | Users with **write** access to that repository |
| See a workspace's tests, data, and settings | Members of the Checksum workspace. SSO sign-in alone doesn't grant access. |

Webhook URLs and bot tokens entered into connectors are masked after creation, and bot tokens are never shown again. The Slack bot can only see channels it has been invited to. Install it only in Slack workspaces your organization owns.

## Revoking access

| To revoke | Do this |
| - | - |
| Repository access | **Settings → Git Integration → Remove Integration**, and/or uninstall the GitHub App or revoke the token at your Git provider. Generation and healing stop working, because Checksum can no longer open PRs. |
| API key | Rotate it in **Settings → Project Settings** |
| An MCP client | **My Profile → MCP connections** |
| A notification connector | Disable or delete it in **Settings → Integrations** |
| SSO sign-in | Entra admin center → Enterprise applications → Checksum → Delete, or assignment changes. For immediate session termination, contact [support@checksum.ai](mailto:support@checksum.ai). |
| Network access | Remove Checksum's IP addresses from your allowlist |

<div className="part bg"><span className="part-icon">i</span><div><div className="part-title">How it works</div><div className="part-sub">User sign-in and related pages</div></div></div>

## Single sign-on

Users can sign in with their company Microsoft account. Checksum requests only `openid`, `email`, and `User.Read` (delegated). It stores only the user's name and email, and holds no Microsoft tokens after sign-in. You can restrict access to assigned users or groups in Entra ID. Full reviewer guide: [Microsoft Entra ID SSO](/docs/sso-entra).

## Related

<CardGroup cols={2}>
  <Card title="Git permissions" icon="code-branch" href="/docs/git-integration#required-permissions">
    Exact scopes per provider and repository type.
  </Card>

  <Card title="Microsoft Entra ID SSO" icon="shield-halved" href="/docs/sso-entra">
    A step-by-step guide for IT reviewers.
  </Card>

  <Card title="Onboarding checklist" icon="list-check" href="/docs/onboarding">
    What to provide before kickoff.
  </Card>

  <Card title="API Keys & Authentication" icon="key" href="/docs/authentication">
    Base URL, headers, and IDs.
  </Card>
</CardGroup>