Skip to main content
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: 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.
The same token reaches the MCP server at https://api.impellabs.tech/mcp. See MCP authentication and API authentication. 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 <area>:read or <area>: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 <area>.<action>, for example agents.edit, knowledge.view or channels.manage. Each is held at one scope: 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 and channels. 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.