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

# API Tokens

> Create and manage CodeAnt API tokens to authenticate CI pipelines and the CodeAnt API.

CodeAnt **API tokens** authenticate you to CodeAnt. Use one anywhere a CI pipeline or a script needs to talk to CodeAnt - coverage upload, automated scans, quality gates, or the REST API.

A single CodeAnt token replaces the per-platform VCS access tokens (GitHub PAT, GitLab token, Bitbucket access token, Azure DevOps PAT) you previously pasted into pipelines. You create it once in CodeAnt and reuse it everywhere.

<Note>
  A CodeAnt token authenticates **to CodeAnt**, not to your Git provider. It always starts with the prefix `cdt_` and is scoped to a single provider + organization.
</Note>

## Create a token

1. Open [CodeAnt AI](https://app.codeant.ai), then open the user menu (click your email at the bottom-left of the sidebar) and select **API Tokens**.
2. Click **Create token**.
3. Check the **Bound to** chip - it shows the provider and organization the token will belong to. Tokens are scoped to the workspace you're currently in, so switch workspaces first if you need a token for a different organization.
4. Give the token a descriptive **name** (for example `ci-coverage` or `automation-token`). Names can be up to 60 characters.
5. Choose the token's **Scope** (optional, but recommended - see [Permissions and scopes](#permissions-and-scopes)):

   * **Role** - pick a role that grants only the permissions the token needs: **Codeant CI/CD** for pipeline tokens (scans, quality gates, coverage), **Codeant Member** for read-only reporting, **Codeant Admin** for full access, or any custom role defined in **Access Control**. Leave it on **Full access (no restriction)** for an unscoped token.
   * **Repositories** - once a role is chosen, restrict the token to specific repositories, or tick **All repositories** to cover the whole organization (including repos added later).

   A token can never grant more than you can access yourself.
6. Click **Create token**.
7. **Copy the token immediately.** It starts with `cdt_` and is shown **only once** - for security, the full value is never displayed again. Store it in your secret manager or CI secret store. CodeAnt only keeps the last 4 characters for identification.

<Warning>
  If you lose a token, you can't recover it - create a new one and revoke the old one.
</Warning>

## Use a token

**CI pipelines**

Add the token to your pipeline as a secret, then pass it as the access-token input of the CodeAnt coverage, scan, or quality-gate step. See:

* [Test coverage uploads](/control_center/test_coverage/github)
* [Automated scans](/control_center/ci/ci_github)
* [Quality gates](/control_center/quality_gates/quality_gate_github)

**REST API**

Send the token as a bearer token in the `Authorization` header:

```bash theme={null}
export CODEANT_API_TOKEN=cdt_xxxxxxxxxxxx   # your CodeAnt token

curl https://api.codeant.ai/... \
  -H "Authorization: Bearer $CODEANT_API_TOKEN"
```

## Permissions and scopes

A token can be limited by a **role** (which product areas / actions it may use) and a **repository scope** (which repos it may touch). Any request outside the token's scope is refused with HTTP `403` and a body like:

```json theme={null}
{
  "code": "token_scope_forbidden",
  "error": "This token is missing CI/CD (read), required for this operation. It currently grants: Code Security (read), Code Quality (read). Update the token's role in Access Control, or use a token that has CI/CD (read)."
}
```

The message distinguishes a **missing permission** from a token that simply **isn't scoped to that repository**.

### Roles

Roles are defined in **Access Control** (Settings → Access Control). Three presets ship by default; admins can also create custom roles.

| Role               | Grants                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------- |
| **Codeant CI/CD**  | Everything a pipeline needs - trigger & read scans, quality gates, and coverage upload |
| **Codeant Member** | Read access to AI Code Review, Code Quality, Code Security, and Cloud Security         |
| **Codeant Admin**  | Full access to every action                                                            |

For a CI/CD pipeline token, **Codeant CI/CD** is the recommended role.

### Repository scope

* **All repositories** - the token works across the whole organization, including repositories added later.
* **Specific repositories** - the token only works on the repositories you select. Any other repository returns `403` with *"This token isn't scoped to `<repo>`"*.

### Permission required per API area

A permission reflects the **product area of the data**, so the same permission gates the dashboard and the API. `cicd` is reserved for pipeline plumbing that has no dashboard equivalent.

| API / operation                                                       | Endpoints                                                                          | Required permission                                         |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Read SAST / SCA / secrets / SBOM results, trigger scans, scan history | `/api/analysis/…`                                                                  | **Code Security** (read)                                    |
| IaC results                                                           | `/api/analysis/results/iac`                                                        | **Cloud Security** (read)                                   |
| Anti-pattern (code quality) results                                   | `/api/analysis/results/antipatterns`                                               | **Code Quality** (read)                                     |
| AI agent scans                                                        | `/api/agents/…`                                                                    | **AI Code Review** (read)                                   |
| DAST scans                                                            | `/analysis/ci/dast/…`                                                              | **Cloud Security** (read)                                   |
| Quality gates, full-scan gate, test-coverage upload                   | `/analysis/ci/quality-gates/…`, `/api/full-scan-gate/…`, `/pr/analysis/coverage/…` | **CI/CD** (read)                                            |
| Team management                                                       | `/api/metrics/developer/teams/…`                                                   | **Organization** (read; **write** for create/update/delete) |
| Engineering / DORA metrics                                            | `/api/metrics/developer/…`                                                         | **Engineering Metrics** (read)                              |
| Account users & subscriptions                                         | `/api/account/…`                                                                   | **Organization** (read; **write** for changes)              |

<Note>
  The **Codeant CI/CD** role covers the entire CI surface above (scans, quality gates, coverage) plus read access to the security/quality areas a pipeline gates on - so a single CI token needs only this one role.
</Note>

### Creator cap & existing tokens

* **A token can never exceed the access of the person who creates it.** If you request more than you have, creation is rejected with a `403` explaining which permission exceeded your access.
* **Backwards compatible:** tokens created before scoping existed - and raw VCS provider tokens (GitHub / GitLab / Bitbucket / Azure DevOps PATs) used directly against the API - keep **full access**. Scoping only applies to new tokens you explicitly scope.

## Manage and revoke tokens

The **API Tokens** page (open the user menu - your email at the bottom-left of the sidebar - and select **API Tokens**) lists every token for the current workspace, each showing a masked value (`cdt_••••last4`), the provider and organization it's bound to, when it was created, and whether it's **Active** or **Revoked**.

To revoke a token, hover over it and click the trash icon, then confirm **Delete token**. Revocation is **immediate and irreversible** - any client still using that token loses access right away.

<Tip>
  To rotate a token without downtime, create the new token first, update your CI secrets to use it, and only then revoke the old one.
</Tip>