> ## 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.

## Create a token

1. Open [CodeAnt AI](https://app.codeant.ai), then go to **Settings → 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.

## 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](https://docs.codeant.ai/control_center/test_coverage/github.md)
* [Automated scans](https://docs.codeant.ai/control_center/ci/ci_github.md)
* [Quality gates](https://docs.codeant.ai/control_center/quality_gates/quality_gate_github.md)

**REST API**

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

```bash theme={"theme":"css-variables"}
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={"theme":"css-variables"}
{
  "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.

### 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 (**Settings → 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.