> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/api-access.md).

# API Access

The RootCause REST API lets you programmatically manage workspaces, datasets, ontology, Digital Twins, simulations, and reports. The **API** page is the hub for all programmatic access. It is where you create and manage API keys, explore the API reference, connect MCP clients, and register OAuth apps.

To open it, go to the Organization home and click the **API** card under Manage.

<figure><img src="/files/FXP82TCkNrHPBqOjhO8T" alt="The Organization home with the API card highlighted under the Manage section"><figcaption><p>The API page lives on the Organization home, under Manage.</p></figcaption></figure>

The page is organized into six sections:

| Section             | Purpose                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Getting Started** | Authentication, code examples, and links to the full API reference                                                                                            |
| **MCP Integration** | Connect Claude Code, Claude Desktop, Claude on the web, Cursor, or any MCP client. See [MCP Integration](/api-and-integrations/api-access/mcp-integration.md) |
| **Connected Apps**  | Assistants and apps you have authorized to reach the organisation — revoke any of them here                                                                   |
| **OAuth Apps**      | Register confidential OAuth clients for third-party apps. See [OAuth Apps](/api-and-integrations/api-access/oauth-apps.md)                                    |
| **Create API Key**  | Generate a new key with fine-grained permission scopes and optional expiry                                                                                    |
| **Manage Keys**     | View, copy, and revoke your existing API keys                                                                                                                 |

***

## Authentication

All API endpoints live under `/api/v1/` on your platform domain. Every request requires a **Bearer token** in the `Authorization` header:

```bash
curl -X GET "https://<your-platform-domain>/api/v1/workspaces" \
  -H "Authorization: Bearer pk_your_api_key_here" \
  -H "Content-Type: application/json"
```

The Getting Started section shows the same example in Python and JavaScript, with your platform's real URL filled in.

<figure><img src="/files/dHFKfScMGb8p2RL0s0xm" alt="The API page with the Getting Started section expanded: the authentication cURL example with Python and JavaScript tabs, and Resources links to the Interactive API Reference and the OpenAPI Specification, above the collapsed MCP Integration, Connected Apps, OAuth Apps, Create API Key, and Manage Keys sections"><figcaption><p>The API page opens on Getting Started: the authentication example in cURL, Python, or JavaScript, with the API reference links below and the other sections stacked underneath.</p></figcaption></figure>

***

## API reference

Two resources are linked from the Getting Started section:

* **Interactive API Reference** (`/api/v1/docs`) explores every endpoint, lets you try requests against your data, and shows request and response schemas.
* **OpenAPI Specification** (`/api/v1/openapi.json`) is the OpenAPI 3.1 spec, which you can feed to a code generator to produce a typed client in your language of choice.

***

## Creating an API key

Open the **Create API Key** section and fill in:

* **Key name** — a label you will recognize later, such as "Production MCP" or "CI Pipeline".
* **Workspace scope** — either **Org-wide** (the key can list and access all workspaces) or a single workspace. Prefer workspace-scoped keys for integrations that only need one project.
* **Permission scopes** — the individual permissions the key carries, grouped by area. Select only what the integration needs; **Select all** exists but should be the exception.

  | Scope area    | Grants                                                | Actions                      |
  | ------------- | ----------------------------------------------------- | ---------------------------- |
  | Sources       | Access and manage uploaded data sources               | read, write, delete          |
  | Datasets      | Read and modify datasets derived from your sources    | read, write, delete          |
  | Ontology      | Browse and edit concepts, relationships, and metadata | read, write, delete          |
  | Digital Twins | Manage causal models and run structural learning      | read, write, delete, execute |
  | Simulations   | View and run what-if simulations on digital twins     | read, execute                |
  | Connectors    | Configure and manage external data connectors         | read, write                  |
  | Catalog       | Browse the workspace data catalog                     | read                         |
  | Jobs          | Monitor background jobs and pipeline runs             | read                         |
  | Exports       | Download generated reports and data exports           | read                         |
  | Agent         | Interact with the AI assistant and MCP tools          | read, write                  |
  | Reports       | Create and view analysis reports                      | read, write                  |

  There is no separate Workspaces scope: listing workspaces is covered by the Sources **read** scope.
* **Expiry** *(optional)* — an end date after which the key stops working. Set one for keys used in CI/CD or temporary scripts.
* **IP allowlist** *(optional)* — a comma-separated list of IPs allowed to use the key. Leave empty to allow all.

<figure><img src="/files/eiNQMPRZhENkmi2obOEa" alt="The Create API Key section with the key name CI Pipeline, workspace scope Org-wide, and the permission scope groups — Sources, Datasets, Ontology, Digital Twins, Simulations, Connectors — with Digital Twins and Connectors ticked, reading 6/24 scopes selected"><figcaption><p>Creating a key: a recognisable name, a workspace scope, and only the permission scopes the integration needs — here 6 of the 24.</p></figcaption></figure>

Click **Create API key**. The new key is displayed after creation; copy it and store it somewhere safe.

***

## Managing keys

The **Manage Keys** section lists every key you have created, filterable by **Org-wide** or **Workspace** scope. From here you can view, copy, and revoke keys.

<figure><img src="/files/S4NFzPmepTLmBsCg07ju" alt="The Manage Keys section listing one key named CI Pipeline with digital-twins:all and connectors:all scopes, Org-wide scope, no expiry, and copy and delete actions, above a Keep your API keys safe callout"><figcaption><p>Manage Keys: every key with its scopes, expiry, last use, and the copy and revoke actions.</p></figcaption></figure>

{% hint style="warning" %}
**Keep your API keys safe.** Never share keys in public channels, repos, or client-side code. Use the narrowest scopes needed for each integration, set an expiry for temporary keys, and rotate keys regularly, deleting any that are no longer needed.
{% endhint %}