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

# API keys

> Create, copy, use, and revoke workspace API keys for Cogno CLI workers.

Use API keys to authenticate Cogno CLI workers for a workspace. API keys are created in the app, copied once, and revoked from workspace settings.

## What an API key is for

Current workspace API keys use the `worker` scope. They are intended for CLI and worker daemon authentication.

| Use case                                           | Supported           |
| -------------------------------------------------- | ------------------- |
| Authenticate `cogno login --token <key>`           | Yes                 |
| Run the root `cogno` worker daemon for a workspace | Yes                 |
| Replace a browser session for a worker daemon      | Yes                 |
| General public API access                          | Not documented here |

## Create a key

1. Open the Cogno app.
2. Select the workspace.
3. Open **Settings > API Keys**.
4. Select **Create**.
5. Enter a name, such as `MacBook worker` or `CI worker`.
6. Select **Create**.
7. Copy the raw key immediately.

The raw key is shown once. After closing the dialog, Cogno only shows key metadata and a prefix.

## Use the key with the CLI

Run:

```bash theme={"system"}
cogno login --token <key>
cogno
```

Then open **Settings > Workers**. The worker should appear after it registers and starts sending heartbeats.

## Key format and limits

| Property         | Value                                                               |
| ---------------- | ------------------------------------------------------------------- |
| Prefix           | `cogno_wk_`                                                         |
| Scope            | `worker`                                                            |
| Active key limit | 25 per user per workspace                                           |
| Raw key storage  | Raw key is not shown again after creation                           |
| List view        | Shows name, prefix, created date, and last used date when available |

## Naming keys

Use names that make revocation decisions obvious.

| Good name                  | Reason                              |
| -------------------------- | ----------------------------------- |
| `alice-macbook-worker`     | Identifies owner and device.        |
| `buildkite-prod-worker`    | Identifies service and environment. |
| `migration-laptop-2026-06` | Identifies temporary use.           |

Avoid names like `test`, `key`, or `worker` when more than one person operates the workspace.

## Store the key

Treat the raw key like a password.

* Store it in a local secret manager, CI secret store, or environment variable.
* Do not paste it into task comments, docs, chat, tickets, or screenshots.
* Do not commit it to a repository.
* Create separate keys for separate machines or services.
* Revoke temporary keys when the task is complete.

## Revoke a key

1. Open **Settings > API Keys**.
2. Find the key by name or prefix.
3. Select the revoke icon.
4. Confirm **Revoke**.

Revocation is immediate and irreversible. Workers using that key lose access immediately. Create a replacement key before revoking when continuity matters.

## Rotate a key

1. Create a new key.
2. Copy and install the new key on the worker machine or service.
3. Restart the worker.
4. Confirm the worker appears in **Settings > Workers**.
5. Revoke the old key.

## Troubleshooting

| Symptom                          | Check                                                                               |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| The raw key is gone              | Create a new key. Existing raw keys cannot be viewed again.                         |
| Create fails                     | Count active keys for your user in this workspace. The limit is 25.                 |
| Worker does not appear           | Run the root `cogno` worker daemon, then check **Settings > Workers**.              |
| Worker was connected and stopped | Confirm the process is still running and the key was not revoked.                   |
| Revoke affected the wrong worker | Create a new key for that worker and log in again with `cogno login --token <key>`. |