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 Toolio — situations where there's no human in the loop to log in interactively. Common use cases:
Connecting an MCP client. Configure Claude, Cursor, Claude Code, or another agent to query planning data through the Toolio MCP Server on a schedule or in response to events.
Headless regression and end-to-end tests. Authenticate automated browser tests (e.g. Playwright, Cypress) against your Toolio workspace via the
/api/auth/automated-loginendpoint, so test runs can sign in without a human entering credentials.
For day-to-day, interactive use of Toolio (e.g. asking Claude questions about your plans, or clicking around the app yourself), sign in with your user account through the 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 With an MCP Client
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.
Using an API Key for Headless Regression Tests
Automated end-to-end tests (Playwright, Cypress, etc.) can exchange an API key for a Toolio session cookie via the /api/auth/automated-login endpoint. The test framework then drives the browser as if a real user had signed in — no interactive login, no shared password.
Send the API key as a bearer token to the workspace's automated-login endpoint:
POST https://<workspace-name>.toolio.com/api/auth/automated-login Authorization: Bearer YOUR_API_KEY
A successful response returns a connect.sid session cookie. Attach that cookie to the browser context for the rest of the test run.
A few practices that work well in CI:
One key per environment. Mint a separate key for each workspace your tests target (e.g. preprod, staging, stress) so a key can be disabled without disrupting the others.
Store keys as CI secrets. Inject them as environment variables at run time rather than checking them into the test repo. A common convention is
TOOLIO_API_KEY_<SUBDOMAIN>so the test harness can pick the right key based on the target host.Use a least-privileged role. Assign the key only the role(s) needed to exercise the screens under test.
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.