Authentication
API keys, OAuth, and which to use.
Two ways for an agent to authenticate. Both end up with the same permissions.
API keys
A long-lived token you paste into a client's configuration.
Create: Settings → API keys → Create. Copy it immediately; it is shown once.
Good for CI, scripts, and clients without OAuth support.
OAuth
Clients that support it can sign in interactively — no key to copy or store. Point the client at your instance URL and it discovers the rest.
Better for people. Sessions can be revoked individually under Settings → Connected agents.
What a key can do
Two limits apply, and the tighter one wins:
- The scopes on the key — read, write, or admin.
- The role of whoever created it, as it stands right now.
That second one matters: if someone is demoted, every key they made drops with them automatically. There is no revocation sweep to run and nothing to remember.
A key can never do more than its creator can do today.
Revoking
Settings → API keys → Revoke. Effective within seconds.
If someone leaves, changing their role removes their keys' power immediately — but revoke the keys too, so nothing is left lying around.
Treat an API key like a password. It carries its creator's access to your company's content. Do not commit one to a repository, and prefer OAuth where the client supports it.