API keys and scopes
Found this helpful? Share it:
Found this helpful? Share it:
An API key lets a script, a server, or a coding agent act as you over the idapt API. Each key carries a set of scopes and an API version, and you can rotate it or cap what it spends 🔑
Open Settings → Developer.
Choose New API key, name it, and pick its scopes.
Copy the key. It starts with uk_and is shown once, so
store it somewhere safe.
Send it on every request as Authorization: Bearer uk_...or in the x-api-key header.
Every signed-in account can hold up to 1000 keys, on the free tier and every plan alike. Model completions through the compatible gateways bill your Credit balance or run on your own provider key; the rest of the API works on every tier. See Rate limits and errors.
A key grants only the scopes you select. Pick the narrowest set that
covers the job: a key that only reads files needs nothing more than
the drive read scope. Every key also needs user:read,
which is granted implicitly. For the full list of scopes and what each
one unlocks, see MCP permissions: the same
scopes apply to REST, the CLI, and MCP.
A key can pin a dated API version, so requests made with it keep the
request and response shapes you built against even as newer versions
ship. A request can still override the pin with an X-Idapt-Version header. See the REST API reference for
how versioning works.
Workspace Gateway keys can carry a spend cap, so a leaked or runaway
key cannot burn your whole balance. Create and cap those on the AI Routing page (/app/ai-routing), alongside
provider routing and bring-your-own-key settings. Personal keys live
under Settings → Developer.
Rotate a key to swap its secret while keeping its name and scopes, which is the safe way to respond to a possible leak. Revoke a key to kill it outright. Both live next to the key in the dashboard.
Key management is cookie-session only: creating, rotating, and
revoking keys work from the dashboard, and the same endpoints return 403 when called with a bearer key. A key can never mint,
rotate, or revoke another key.
| Endpoint | What it does |
|---|---|
GET /api-keys | List API keys. |
POST /api-keys | Create an API key. |
PATCH /api-keys/:id | Update an API key (name/scopes). |
DELETE /api-keys/:id | Revoke an API key. |
POST /api-keys/:id/rotate | Rotate an API key's secret. |
Related articles
REST API
Authentication, versioning, response shapes, pagination, and errors for the idapt REST API, plus the full endpoint list.
MCP permissions
API key scopes, what each one grants, and how to pick the narrowest set for your workflow.
Rate limits and errors
Every error shape the API returns, what each rate limit is, and how to handle a wall in code.
Was this helpful?