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

# API Keys & Service Accounts

> Create, rotate, and revoke API keys and service accounts for programmatic access to Causeloop.

Causeloop provides two types of machine credentials for API access:

* **Personal API tokens (PATs)** — scoped tokens tied to your user account. Use them for personal scripts, local development, and tooling that acts on your behalf.
* **Service accounts** — workspace-level principals with their own identity and tokens. Use them for CI/CD pipelines, backend integrations, and any process that should not be tied to a specific person.

Open the API Keys screen from the sidebar: **Settings → API Keys**.

<Note>
  To learn how to authenticate API requests with a token, see [API Reference → Authentication](/api-reference/authentication).
</Note>

***

## Personal API tokens

### Create a token

<Steps>
  <Step title="Click + New API token">
    The token creation dialog opens.
  </Step>

  <Step title="Give the token a name">
    Choose a descriptive name (e.g. `local-dev`, `grafana-integration`). Names must be unique within your account.
  </Step>

  <Step title="Select scopes">
    Check the scopes the token should have. Only grant scopes the integration actually needs.
  </Step>

  <Step title="Set an expiry (optional)">
    Tokens are long-lived by default. Set an expiry date if the token is for a short-lived use.
  </Step>

  <Step title="Copy the secret">
    The token secret is shown **once** immediately after creation. Copy it now and store it in a secrets manager. Causeloop only stores a hash of the secret and cannot display it again.
  </Step>
</Steps>

### Rotate a token

Click **Rotate** on any token row. Causeloop issues a new secret and immediately invalidates the old one. Copy the new secret from the dialog before closing it.

<Warning>
  Rotating a token invalidates the old secret immediately. Update all integrations using the old token before rotating.
</Warning>

### Revoke a token

Click **Revoke** on a token row. The token is invalidated immediately and all subsequent requests using it return `401 unauthorized`. Revoked tokens cannot be re-activated; create a new token if you need access again.

***

## Available scopes

Use the minimum scopes necessary for the integration. You can retrieve the current scope catalogue from `GET /v1/api-tokens/scopes`.

<Tabs>
  <Tab title="Data">
    | Scope                   | Description                    |
    | ----------------------- | ------------------------------ |
    | `issues:read`           | Read issues and their analysis |
    | `issues:write`          | Create and update issues       |
    | `patterns:read`         | Read patterns                  |
    | `patterns:write`        | Write patterns                 |
    | `predictions:read`      | Read predictions               |
    | `predictions:write`     | Write predictions              |
    | `recommendations:read`  | Read recommendations           |
    | `recommendations:write` | Write recommendations          |
  </Tab>

  <Tab title="Integrations">
    | Scope               | Description                   |
    | ------------------- | ----------------------------- |
    | `connectors:read`   | View connectors               |
    | `connectors:write`  | Create and update connectors  |
    | `connectors:admin`  | Administer connectors         |
    | `webhooks:read`     | View webhooks                 |
    | `webhooks:write`    | Create and update webhooks    |
    | `webhooks:admin`    | Administer webhooks           |
    | `alert-rules:read`  | Read alert rules              |
    | `alert-rules:write` | Create and update alert rules |
  </Tab>

  <Tab title="Workspace">
    | Scope              | Description                       |
    | ------------------ | --------------------------------- |
    | `workspace:read`   | Read workspace profile            |
    | `workspace:write`  | Update workspace settings         |
    | `members:read`     | List workspace members            |
    | `members:write`    | Invite members and change roles   |
    | `audit:read`       | Read the audit log                |
    | `api-tokens:read`  | List API tokens                   |
    | `api-tokens:write` | Create, rotate, and revoke tokens |
    | `governance:read`  | Read data governance policies     |
    | `governance:write` | Edit data governance policies     |
    | `exports:read`     | Read exports                      |
    | `exports:write`    | Trigger exports                   |
  </Tab>

  <Tab title="AI & Reports">
    | Scope                 | Description                   |
    | --------------------- | ----------------------------- |
    | `reports:read`        | Read and download reports     |
    | `reports:write`       | Generate and schedule reports |
    | `ai:read`             | Read AI model outputs         |
    | `ai:write`            | Configure AI settings         |
    | `ai:run`              | Trigger AI analysis runs      |
    | `orchestration:read`  | Read orchestration jobs       |
    | `orchestration:run`   | Trigger orchestration runs    |
    | `orchestration:write` | Configure orchestration       |
    | `orchestration:admin` | Administer orchestration      |
  </Tab>

  <Tab title="Admin">
    | Scope   | Description                                                            |
    | ------- | ---------------------------------------------------------------------- |
    | `admin` | Full workspace administration access. Use only for trusted automation. |
  </Tab>
</Tabs>

***

## Service accounts

Service accounts are workspace-level machine principals. Unlike personal tokens, they are not tied to any user and remain active even if the user who created them leaves the workspace.

Creating and managing service accounts requires the `workspace:admin` scope (Tenant Admin role).

### Create a service account

<Steps>
  <Step title="Click + New service account">
    The service account creation dialog opens.
  </Step>

  <Step title="Enter a name and description">
    Names must be unique within the workspace (case-insensitive).
  </Step>

  <Step title="Select scopes">
    Choose the scopes this service account's tokens will be allowed to use.
  </Step>

  <Step title="Save">
    The service account is created. It starts with no tokens.
  </Step>
</Steps>

### Issue a token for a service account

Once the service account is created, click **Issue token** on its row.

* Give the token a name.
* The token secret is shown **once**. Copy it immediately.
* Tokens are associated with the service account's scopes at issuance time. Changing the service account's scopes does not update already-issued tokens.

### Revoke a service account token

Click **Revoke** on an individual token entry under the service account. The token is invalidated immediately.

### Delete a service account

Click **Delete** on a service account row. All tokens associated with the account are revoked immediately.

***

## API endpoints

| Method   | Path                                        | Description                    |
| -------- | ------------------------------------------- | ------------------------------ |
| `GET`    | `/v1/api-tokens`                            | List personal API tokens       |
| `POST`   | `/v1/api-tokens`                            | Create a personal API token    |
| `POST`   | `/v1/api-tokens/{id}/roll`                  | Rotate a token secret          |
| `DELETE` | `/v1/api-tokens/{id}`                       | Revoke a token                 |
| `GET`    | `/v1/api-tokens/scopes`                     | List all available scopes      |
| `GET`    | `/v1/service-accounts`                      | List service accounts          |
| `POST`   | `/v1/service-accounts`                      | Create a service account       |
| `DELETE` | `/v1/service-accounts/{id}`                 | Delete a service account       |
| `POST`   | `/v1/service-accounts/{id}/tokens`          | Issue a service account token  |
| `DELETE` | `/v1/service-accounts/{id}/tokens/{tok_id}` | Revoke a service account token |

For the full REST specification and how to use tokens in requests, see [API Reference → Authentication](/api-reference/authentication).