> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Access and keys
> Tokens, scopes and what each role can reach.
A token lets your code act as one member of one workspace. It has that member's access and no more. If the member's role changes, the token changes with it. If the member is removed, the token stops working.
## Make a token
A member makes a token in the ImpelLabs app, in Settings, while signed in. Tokens are made and revoked only from a signed-in session, never with a token.
The request that the app sends is `POST /api/v1/api-tokens`:
| Field | Meaning |
| - | - |
| `name` | Required. A label up to 80 characters, such as "Claude on my laptop". |
| `expires_in_days` | Optional. A whole number from 1 to 366. Without it the token has no end. |
| `scopes` | Optional. See below. |
The answer holds the `token` once. It starts with `imp_`. ImpelLabs keeps only a hash of it, so it cannot show the token again. Store it as a secret.
A member can have a limited number of live personal tokens. Revoke the ones you do not use.
## Use a token
Send it as a bearer token. The token names its workspace, so no workspace header is needed.
```bash theme={null}
curl https://api.impellabs.tech/api/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY"
```
The same token reaches the MCP server at `https://api.impellabs.tech/mcp`. See [MCP authentication](https://docs.impellabs.tech/connect/authentication.md) and [API authentication](https://docs.impellabs.tech/api/authentication.md).
A token cannot reach sign-in, workspace and token routes. These need a signed-in session, and a request with a token is refused.
An assistant that supports web sign-in gets its own token through a sign-in screen where the member says yes. That token reaches only the MCP server. It lasts an hour and is renewed with a refresh token. Revoking it ends the whole grant.
## Scopes
A scope limits which tools a connection to the MCP server can call. A scope is `:read` or `:write`. The area is the part of ImpelLabs a tool belongs to. Tools that only read need the `read` scope. Tools that write, send, spend or go live need the `write` scope.
* A token made with no scopes reaches every tool.
* `mcp` means every scope.
* An unknown scope is refused.
A token with scopes cannot call a tool outside them. The call is refused and says to allow it again with more access. `tools/list` only lists the tools the token may call.
## Roles and capabilities
What a member can do comes from their role. A capability has the form `.`, for example `agents.edit`, `knowledge.view` or `channels.manage`. Each is held at one scope:
| Scope | Reach |
| - | - |
| `own` | What the member owns or added. |
| `department` | What belongs to a department they manage, and their own. |
| `workspace` | Everything. |
Owners and admins hold every capability at `workspace`. A manager and a member hold the same preset: they see the team, departments, agents and knowledge of the workspace, manage what they own, and see and connect their own channels. They can see and add records in apps.
A workspace can make custom roles and give a member overrides. An override sets a capability at a scope, or `deny` to take it away. `deny` wins.
On top of roles, agents and channels are private to their owner until shared. See [agents](https://docs.impellabs.tech/guides/agents.md) and [channels](https://docs.impellabs.tech/guides/channels.md). Owners and admins keep oversight of agents but not their content.
## Revoke a token
A member revokes their own tokens. An owner or an admin can revoke any token in the workspace. A revoked token stops at once.
## Limits
The MCP endpoint accepts 120 requests each minute for each token. Over the limit the answer is `429` with `retry_after` in seconds. See [limits](https://docs.impellabs.tech/connect/limits.md).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.