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

# API Keys

> Create API applications and generate keys that let external systems call the Kodda REST API.

API Keys let external systems — schedulers, CI pipelines, orchestration tools, scripts — call the Kodda REST API without a browser login. Keys are grouped under **API Applications**, so you can issue one or more keys to each integrating system and revoke them independently.

> [!NOTE]
>
> API Keys are available to users in the **Admin** group only. Open them from the **Manage** menu in the top navigation.

![API Keys under the Manage menu](https://mintcdn.com/cao-analytics-llc/Wl3vvTuZGchqkbbo/images/api-keys-manage-menu.jpg?fit=max\&auto=format\&n=Wl3vvTuZGchqkbbo\&q=85\&s=666a30f82f4f7ae142dbbf115bde1e67)

## How it works

* An **API Application** represents one integrating system (for example, "Airflow" or "Nightly Reporting"). It has a name, an optional description, and an active flag.
* Each application can hold any number of **API Keys**. A key is a string beginning with `kodda_` that the caller sends as a Bearer token.
* Kodda stores only a hash of each key. The full key is shown **once**, at the moment it is generated, and cannot be retrieved later. If a key is lost, revoke it and generate a new one.
* Keys can be **revoked** individually. Deactivating an application revokes all of its keys at once.
* Requests made with an API key run with full access to the external API; they are not restricted by the role of the admin who created the key.

## API Applications screen

The API Applications screen lists every application, the number of active keys it holds, who created it, and whether it is active.

![API Applications list](https://mintcdn.com/cao-analytics-llc/Wl3vvTuZGchqkbbo/images/api-keys-applications.jpg?fit=max\&auto=format\&n=Wl3vvTuZGchqkbbo\&q=85\&s=4a10410c36b35ed122868e6db34de736)

* Click the **+** icon in the table header to create a new application.
* Click the key icon on a row to view and manage that application's keys.
* Click the trash icon on a row to **deactivate** the application. This revokes all of its keys; any integration using them will start receiving `401` responses immediately.

### Create an application

Clicking **+** opens the Create API Application form. Enter a name (required, must be unique) and an optional description, then click **Create**.

![Create API Application form](https://mintcdn.com/cao-analytics-llc/Wl3vvTuZGchqkbbo/images/api-keys-create-application.jpg?fit=max\&auto=format\&n=Wl3vvTuZGchqkbbo\&q=85\&s=e3637b546c979bab84cf359a3f3a8928)

### View and manage keys

Clicking the key icon on an application row opens its key list. For each key you can see the first characters of the key (the *prefix*, useful for matching a key to the system that holds it), when it was created, when it was last used, and whether it is active.

![Keys for an application](https://mintcdn.com/cao-analytics-llc/Wl3vvTuZGchqkbbo/images/api-keys-key-list.jpg?fit=max\&auto=format\&n=Wl3vvTuZGchqkbbo\&q=85\&s=1f29ccc37e80f7e0f4b941bcac893ed4)

* Click **+** to generate a new key for this application.
* Click the revoke icon on a key row to deactivate it. You will be asked to confirm. Revoked keys remain in the list, marked **No** under Active, so you keep a record of what was issued.

### Generate a key

When you generate a key, Kodda shows the full key value one time.

![API Key Generated dialog](https://mintcdn.com/cao-analytics-llc/Wl3vvTuZGchqkbbo/images/api-keys-key-generated.jpg?fit=max\&auto=format\&n=Wl3vvTuZGchqkbbo\&q=85\&s=adaf3da5ac7a130ae7a2e843418caa20)

> [!WARNING]
>
> Copy the key before closing this dialog. It is not stored anywhere in Kodda and will not be shown again. If you close the dialog without copying it, revoke the key and generate a new one.

Use the **Copy** button to put the key on your clipboard, then store it in your integration's secret store.

## Using an API key

Send the key as a Bearer token in the `Authorization` header. API keys are accepted only on the external API, under `/kodda/api/v1/`.

```bash theme={null}
curl -H "Authorization: Bearer kodda_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://your-kodda-host/kodda/api/v1/workflows/executions
```

Endpoints available to API keys include:

| Endpoint | Description |
| - | - |
| `GET /kodda/api/v1/workflows/executions` | Workflow execution history |
| `GET /kodda/api/v1/workflows/<wf_id>/executions` | Execution history for one workflow |
| `GET /kodda/api/v1/workflows/executions/<id>/tasks` | Tasks within a workflow execution |
| `GET /kodda/api/v1/maps/executions` | Mapping execution history |
| `GET /kodda/api/v1/maps/<map_id>/executions` | Execution history for one mapping |
| `GET /kodda/api/v1/tasks/<task_id>/status` | Status of a running task |
| `/kodda/api/v1/scheduler`, `/kodda/api/v1/scheduler/jobs` | Scheduler and scheduled jobs |
| `/kodda/api/v1/import`, `/kodda/api/v1/import/list` | Import mappings and workflows |

See the [API Docs](http://apidocs.caoanalytics.com) for request and response details.

A request is rejected with `401 Invalid or expired API key` when the key has been revoked or belongs to a deactivated application. A request to a path outside `/kodda/api/v1/` with a Bearer token is rejected with `403`.


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