# API keys

> Workspace API keys for servers, scripts and the app CLI.

Source: https://docs.coline.app/authentication/api-keys

A workspace API key lets a server or script call the Coline API without a person signing in. Each key belongs to one workspace, carries a fixed set of [scopes](/authentication/scopes), and acts as the workspace rather than as a member.

## Create a key

1. Open the [developer console](https://coline.app/developers/console) and choose a workspace.
2. Go to **API keys** and create a key.
3. Name the key and pick its scopes.
4. Copy the key. It's shown once. Coline stores only a hash, so a lost key can't be recovered; revoke it and create a new one.

Only the workspace owner and admins can create or revoke keys. Keys start with `col_ws_`.

## Use a key

Send it as a bearer token:

```bash
curl https://coline.app/api/v1/workspaces/acme/sheets \
  -H "Authorization: Bearer col_ws_..."
```

The workspace in the URL must be the key's workspace, by slug or ID. A key for another workspace gets `403 API_KEY_WORKSPACE_MISMATCH`.

## What a key can and can't do

A key can call any route whose required scopes it holds. See the [endpoint reference](/api/endpoints) for the scope each route needs.

A key has no person behind it, so some routes refuse it with `403 USER_IDENTITY_REQUIRED`:

* calendar routes, which act on a person's calendars and invitations
* message, DM and thread routes, which only show conversations a person is in (keys can list public channels)
* `GET /api/v1/me/workspaces` and `GET /api/v1/oauth/userinfo`

Use an [OAuth token](/authentication/oauth) for those.

Writes made with a key are recorded in the workspace audit log against the key, not a member.

## Rate limits

Each key gets 300 read requests and 60 write requests per minute. See [rate limits](/api/rate-limits).

## Revocation

A key stops working as soon as an admin revokes it in the console. There is no grace period. Rotate a key by creating the new one, deploying it, then revoking the old one.

## Keys in the app CLI

The app CLI (`coline-app push`) reads a key with the `apps.write` scope from `COLINE_API_KEY`. Keep keys out of source control and app bundles; set them in your environment or secret store. See [develop locally](/sdk/publishing#develop-locally).