Senso Documentation — The Trusted AI Answer

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 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 page	Never, unless you set an expiry date	Full, or restricted to parts of your knowledge base
CLI key	Run `senso login` 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

On the API Keys page, click + New key.
Enter a Name, for example Production key.
Optionally, pick an Expiry date. Leave it empty for a key that never expires.
Click Create key.
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:

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

Removing every restriction gives the key full access again.

Rotate a key

Create a new key with the same access.
Switch your integration to the new key.
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.

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 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.

Next steps

Send your first API request — Use a key in a real request, start to finish
Permissions — Roles, key scopes and knowledge base access
Senso CLI — Sign in with senso login
Errors — Every status the API returns