A Toolio API Key is the credential a machine client uses to authenticate to Toolio's MCP server. The key is presented as a bearer token on each request and is scoped to your workspace, with permissions determined by the roles you assign when you create it.
When to Use an API Key
API keys are for machine-to-machine access to the Toolio MCP Server — situations where there's no human in the loop to log in interactively. The most common use case is building an agent that connects to MCP to query planning data on a schedule or in response to events.
For day-to-day, interactive use of the MCP server (e.g. asking Claude or Cursor questions about your plans), sign in with your Toolio user account through the MCP client's normal authentication flow rather than using an API key.
Creating an API Key
API keys are managed in Settings > Organization Settings > API Keys.
Navigate to Settings > Organization Settings > API Keys.
Click
Add API Key.Enter a Name that identifies the client (e.g.
claude-desktop-jane,forecasting-agent). The name appears in the API Keys table and in audit logs.Select one or more Roles to grant the key. The key inherits the combined permissions of the selected roles, the same way a user account does. Pick the least-privileged role(s) the client needs.
Click
Save. Toolio generates the key and displays the full value once. Copy it immediately and store it in a secrets manager or your AI client's secure credential store.
After creation, the API Keys table shows the key's Name, a truncated preview of the key value (e.g. tak_bUiB...), the assigned Roles, and its Status. The full key value is never shown again — if you lose it, disable the old key and create a new one.
Using an API Key
Configure your MCP client (Claude, Cursor, Claude Code, etc.) with the key in the headers block of its MCP configuration:
{
"mcpServers": {
"toolio": {
"type": "http",
"url": "https://<workspace-name>.toolio.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Replace <workspace-name> with your Toolio subdomain and YOUR_API_KEY with the key you copied at creation. For step-by-step setup of each client, see Connecting to Toolio MCP Server.
Enabling, Disabling, or Rotating a Key
Keys are enabled and disabled from the same API Keys page. Right-click the row for the key you want to change and select Disable or Enable from the context menu. The key's Status updates immediately — disabled keys are rejected on the next request, and re-enabling a key restores access without changing its value.
To rotate a key, create a new key with the same roles, update each client to use the new key, confirm it works, and then disable the old one.
Security Best Practices
Don't share keys between people or clients. Create a separate key per integration so that disabling one doesn't disrupt the others.
Don't commit keys to source control. Use environment variables, a secrets manager (1Password, AWS Secrets Manager, Azure Key Vault, etc.), or your AI client's secure credential store.
Use the least-privileged role(s). Give a key only the roles its client actually needs.
Rotate keys when team members leave or when a key may have been exposed.
FAQs
Where do I create an API Key?
Go to Settings > Organization Settings > API Keys and click Add API Key. You'll need permission to access organization settings.
Can I see the full API Key value after I create it?
No. The full key value is shown once at creation time and never again — only the tak_… prefix is displayed in the table afterwards. If you lose the value, disable the old key and create a new one.
What permissions does an API Key have?
A key inherits the combined permissions of the roles you assign to it. Those roles determine which data the key can access when it queries the MCP server — what the key can actually do in practice is also bounded by the capabilities the MCP server itself exposes.
How do I disable or re-enable an API Key?
On the API Keys page, right-click the key's row and select Disable or Enable. Disabled keys are rejected on the next request; re-enabling a key restores access using the same value.
How is an API Key different from logging in to Toolio?
A login authenticates a person interactively. An API key authenticates a machine client non-interactively and is intended for agents connecting to the MCP server.