> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.cxplanner.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Set up API access

## Overview: set up API access

The company **API** area lets **Admin** users create API keys and OAuth clients so external systems, scripts, or internal tools can call CxPlanner over HTTPS, which is used for integrations that need read, write, or global project access.

For assigning an API user to a project, see [Add an API user to a project](https://help.cxplanner.com/en-us/article/add-an-api-user-to-a-project-8mstyy/).

* Your role must be company **Admin**.
* You can find the menu at profile icon - **Company profile** - **API**.
* This creates or revokes credentials that can access company and project data.

|| Only users with the company role **Admin** can access and manage the **API** area.

|| The **API key** module is an Enterprise feature and must be enabled for your company.

Secrets are shown only once. Non-global integrations need project membership for the API user. Global access covers all company projects without per-project setup.

## How to set up API access

### Open the API keys page
1. Sign in to CxPlanner and click your profile icon.
2. Go to **Company profile**.
3. Click **API**.

![Screenshot: Company API keys page](https://storage.crisp.chat/users/helpdesk/website/-/e/a/2/c/ea2cfd7bb6130800/image_1pm2zmb.png)

### Create a new API key or OAuth client
1. Click **Generate API key** at the bottom of the screen.
2. In **Create new API key**, enter an **API name**.
3. Choose an **API type**.
4. Choose an **API scope**.
5. Click **Save**.

![Screenshot: Create new API key dialog with name, type, and scope](https://storage.crisp.chat/users/helpdesk/website/-/e/a/2/c/ea2cfd7bb6130800/image_1c95n8c.png)

### Store credentials securely
1. Identify the credential type created.
2. For a static API key, copy the secret from the dialog.
3. For OAuth types, copy **Client ID** and **Client Secret**.
4. Store them in your secret manager before closing the dialog.

||| Secrets are only shown once. If lost, create a new key or client and delete the old one.

### Manage existing credentials
1. Open the table on the **API keys** page.
2. Review **Name**, **Scope**, **Type**, **Last used**, and **Used (count)**.
3. Locate the key or client to remove.
4. Click **Delete**.
5. Confirm in the **Delete API key** dialog.

![Screenshot: API keys table with delete action](https://storage.crisp.chat/users/helpdesk/website/-/e/a/2/c/ea2cfd7bb6130800/image_1nyye38.png)

### Grant project access for scoped API users
1. Confirm the integration uses a non-global scope.
2. Identify the API user (`apiservice+<unique_id>@cxplanner.com`).
3. Open each relevant project.
4. Add the API user with a suitable project role.
5. Match the role to what the integration needs.

## Results: API access

### Authentication types

| Authentication type | Use case | How it works | Typical usage |
|---|---|---|---|
| Static API key | System-to-system | Send key in header, for example `Authorization: Apikey YOUR_STATIC_KEY` | Simple integrations |
| OAuth (API user) | System-to-system | Use client_id and client_secret to obtain Bearer tokens (client_credentials) | Standard secure integrations |
| OAuth PKCE (individual user) | User-delegated | User logs in and approves access, then API uses a Bearer token | User-based integrations |

### Scope behavior

| Scope (create dialog) | Table label | Access |
|---|---|---|
| Developer READ API | READ ONLY | Read access only |
| Developer READ-WRITE API | READ and WRITE | Read and write access |
| Developer Global API | GLOBAL | Access to all company projects |

### Project access rules

| Scope type | Project access required | Result |
|---|---|---|
| READ API | Yes | Can read data in assigned projects |
| READ-WRITE API | Yes | Can read and write in assigned projects |
| GLOBAL | No | Access to all company projects |

|| Static API keys do not expire. Bearer tokens last about 3600 seconds and include a refresh token.

## Troubleshooting: set up API access

| Problem | Cause | Solution |
|---|---|---|
| API menu is missing | API module not enabled, or role is below Admin | Ask a **Company Admin** to enable the API key module or raise your role to **Admin** |
| Cannot click Generate API key | API feature not enabled for the company | Ask a **Company Admin** or CxPlanner Support to enable the API key module |
| Error opening the API page | Account is not company Admin | Sign in with a **Company Admin** account |
| Integration cannot access a project | API user not added, or wrong scope | Add the API user to the project and confirm the key scope |
| Lost API secret | Secrets are shown only once | Create a new key, update integrations, delete the old key |
| Integration cannot write data | Read-only scope selected | Create a key with Developer READ-WRITE API scope |
| Integration cannot access all projects | Not using global scope | Create a key with Developer Global API scope, or add the API user to each project |