# Working with API Keys

How Senso API keys work, what a key can reach, and how to create, restrict, rotate and revoke one.

Senso uses API keys to authenticate requests from your agents, scripts and integrations, and to decide which organization a request acts on. **Every key is secret and belongs to exactly one organization.**

Create and manage keys on the [API Keys](https://docs.senso.ai/api-keys) page. If you use the CLI, `senso login` creates one for you. A request with a missing, wrong, expired or revoked key gets a `401`.

## Key types

Senso has one kind of key. It always starts with `tgr_`. What differs is how you got it.

| Key | How you get it | Expires | Access |
|-----|----------------|---------|--------|
| **API key** | Create it on the [API Keys](https://docs.senso.ai/api-keys) page | Never, unless you set an expiry date | Full, or restricted to parts of your knowledge base |
| **CLI key** | Run [`senso login`](https://docs.senso.ai/docs/senso-cli) and approve it in your browser | After 7 days | Full |

A CLI key is named after the device that asked for it, like `senso-cli my-laptop 2026-09-30`, so you can tell it apart on the API Keys page.

## What a key can do

**A key has the full permissions of its organization**, whatever the role of the person who created it. It can ingest, search, generate and publish for that organization, and nothing outside it.

**A key cannot manage keys.** Creating, changing, restricting and revoking keys all need a signed-in person on the API Keys page. That way a leaked or restricted key cannot create itself a more powerful one.

**Knowledge base access is the one thing you can restrict.** A key with no restriction can read and write your whole knowledge base. You can limit it to chosen folders and documents, as a viewer or an editor of each. See Restrict a key, below.

## Send a key

Send the key in the `X-API-Key` header on every request:

```bash
curl "https://apiv2.senso.ai/api/v1/org/me" \
  -H "X-API-Key: $SENSO_API_KEY"
```

## Protect your keys

Anyone holding an unrestricted key can read and change everything your organization has in Senso.

- Keep keys on a server, in an environment variable or a secrets manager. Never put one in browser or mobile code.
- Don't commit keys to source control, and don't paste them into email or chat.
- Use a separate key for each integration or environment, so you can revoke one without breaking the others.
- Restrict a key to the parts of your knowledge base it needs.
- Set an expiry date on keys that only need to exist for a while.
- Revoke keys you no longer use, and rotate keys when someone with access to them leaves.

## Manage your API keys

**Only admins can manage keys.** The API Keys page shows for admins only. A custom role can be given API key permissions too.

### Create a key

1. On the [API Keys](https://docs.senso.ai/api-keys) page, click **+ New key**.
2. Enter a **Name**, for example `Production key`.
3. Optionally, pick an **Expiry** date. Leave it empty for a key that never expires.
4. Click **Create key**.
5. Copy the key and store it somewhere safe.

> The key is shown only once. Senso stores a hash of it, not the key, so it cannot be shown again. If you lose a key, revoke it and create a new one.

### Restrict a key

New keys have **Full access**. To limit one to part of your knowledge base:

1. On the API Keys page, click **Configure KB scope** on the key.
2. Choose the folders and documents the key can reach.
3. Click a role badge to switch between **Viewer** and **Editor**.
4. Save. The key now shows as **Restricted**.

Removing every restriction gives the key full access again.

### Rotate a key

1. Create a new key with the same access.
2. Switch your integration to the new key.
3. Revoke the old key once nothing uses it.

### Revoke a key

Click **Revoke** on the key. It stops working immediately and cannot be restored. **Delete** does the same thing and also removes the key from the list.

## Keys from the CLI

`senso login` creates a CLI key through your browser, so you never have to copy or paste a key. You must be an administrator to go through this flow. The CLI then stores the key locally.

If you are not an administrator, ask one for an API key and sign in with it instead:

```bash
senso login --api-key <key>
```

The CLI checks the key with Senso before storing it, and a key that is rejected is not stored.

| | CLI key |
|---|---|
| **Lifetime** | 7 days. Run `senso logout` and then `senso login` to get a new one. |
| **Access** | Full. The organization is the one the approving admin has selected. |
| **Sign out** | `senso logout` revokes the key, then forgets it. |
| **Your own key** | `senso login --api-key <key>` stores a key you created instead. `senso logout` forgets it but does not revoke it, since it may be in use elsewhere. |

The CLI reads a key from `--api-key` first, then the `SENSO_API_KEY` environment variable, then its stored config. `senso whoami` shows which one it used. See [Senso CLI](https://docs.senso.ai/docs/senso-cli).

## When a key fails

| Status | What it means | What to do |
|--------|---------------|------------|
| `401` | The key is missing, wrong, expired or revoked. | Check the header, or create a new key. |
| `403` "This action requires user authentication" | You used a key for something only a signed-in person can do, like creating or revoking keys. | Do it on the [API Keys](https://docs.senso.ai/api-keys) page. |
| `403` | A restricted key can see that folder or document, but as a viewer it cannot change it. | Make the key an editor there, or use another key. |
| `404` | The key is restricted, and what you asked for is outside its scope. Senso answers as if it does not exist. | Widen the key's scope, or use another key. |

Every other status is on [Errors](https://docs.senso.ai/docs/errors).

## Next steps

- [Send your first API request](https://docs.senso.ai/docs/quickstart) — Use a key in a real request, start to finish
- [Permissions](https://docs.senso.ai/docs/permissions) — Roles, key scopes and knowledge base access
- [Senso CLI](https://docs.senso.ai/docs/senso-cli) — Sign in with `senso login`
- [Errors](https://docs.senso.ai/docs/errors) — Every status the API returns