Skip to main content
An API key authenticates one machine, or the Cogno CLI on it, against a workspace — without a browser session. Create the key in the app, copy it once, install it on the machine, and revoke it from workspace settings when the machine is done.

​
Prerequisites

  • A workspace role that can create keys — Member, Admin, or Owner. A Viewer does not see Settings → API Keys.
  • The Cogno CLI installed on the machine that will use the key.

​
What an API key is for

​
Create a key

1

Open the page

Open Cogno, select the workspace, and open Settings → API Keys.
2

Start a key

Select Create. The Create API key dialog opens.
3

Name it

Fill in Name (optional) — something like alice-macbook or ci-runner — and select Create.
4

Copy it now

API key created shows the raw key with a copy button, and the command to use it with. Copy it, then select Done.
The raw key is shown once. After the dialog closes, Cogno only shows the key’s name, prefix, and dates — there is no way to read the key again.

​
Use the key on a machine

Run this on the machine:
To confirm the machine is authenticated, run:
The credential check reports workspace API key, and backend names the workspace the key authenticates against.
A server that runs work in the background does not use an API key. Setting it up from Settings → Machines, or running cogno server install on it, enrolls the machine and issues it a machine credential of its own. See Connect to a remote server.

​
What the list shows

Each row carries the key’s identity and history, so you can decide what to revoke without opening anything. Admins and Owners get a filter above the list: My keys shows their own, All workspace keys shows every member’s with the owner’s name on each row.

​
Key format and limits

​
Naming keys

Use names that make revocation decisions obvious. Avoid names like test, key, or machine 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 work is finished.

​
Revoke a key

1

Find the key

Open Settings → API Keys and find the key by name or prefix.
2

Revoke it

Select the trash icon on the row — its label is Revoke <name>. The row asks to confirm: “Revoke this key? Machines using it will lose access immediately.” Select Revoke.
Revocation is immediate and irreversible. Any machine using that key loses access at once. Create a replacement key first when the machine must keep working.
A member revokes their own keys. An Admin or Owner can revoke any key in the workspace from All workspace keys.

​
Rotate a key

1

Create the replacement

Create a new key and copy it.
2

Install it

On the machine, run cogno login --token <new key> to replace the stored credential.
3

Confirm

Run cogno doctor on the machine and check that credential and backend both pass.
4

Retire the old key

Revoke the old key in Settings → API Keys.

​
Troubleshooting

For anything not listed here, see Troubleshooting.