API Keys
The Tiro API uses API keys for authentication. Every request carries a valid key in theAuthorization header as a Bearer token.
Each key belongs to a workspace. The key reaches that workspace’s resources — its notes, transcripts, summaries, and folders — and nothing outside it. Pick the workspace first, then create the key.
Key types and permissions
Tiro API keys fall into two types, based on who the request represents.| Key type | How it is identified | What it can do |
|---|---|---|
| User key | The key is tied to a specific user identity. | Use it for read and write operations. Actions that change workspace data, such as creating note documents or changing share links, require a user key. |
| Workspace system key | The key is tied to the workspace container without a user. | Use it for read access to resources shared with the whole workspace. It cannot perform write operations. |
If a workspace system key is not bound to a workspace yet, authentication may fail with
401 Unauthorized. If the key format is correct but 401 responses continue, check which workspace the key is connected to and where it was created.Getting Your API Key
Create your key from the Tiro Platform dashboard:Sign in
Pick a workspace
Choose the workspace whose data the key should reach, using the workspace switcher in the sidebar. The key is scoped to this workspace only.
Create a key
Click Create New API Key, name it, and copy the full key including the dot —
abc123.xR7mK9pL2qW4....API Key Format
Tiro API keys follow this format:abc123.xR7mK9pL2qW4...
| Part | Example | Description |
|---|---|---|
Key ID ({id}) | abc123 | Visible in Platform dashboard. Used to identify which key is making requests. |
Secret ({secret}) | xR7mK9pL2qW4... | Shown only once at creation. The server stores only a hash — it cannot be recovered. |
| Full API Key | abc123.xR7mK9pL2qW4... | The entire string including the dot. This is what you use as the Bearer token. |
Making Authenticated Requests
Include your API key in theAuthorization header of every request:
Authentication Errors
If authentication fails, you’ll receive a401 Unauthorized response. Common reasons include:
- Missing Authorization header
- Malformed key (must be
{id}.{secret}) - Unknown key id
- Inactive, expired, or deleted key
Legacy personal keys (deprecated)
Before workspaces, a personal API key was tied to your account, not a workspace. Those personal keys are deprecated. Team keys now come through as workspace keys — each team maps to a workspace. Workspace keys replace both.| Legacy personal key | Workspace key | |
|---|---|---|
| Scope | Account-wide | One workspace |
| Create new | Disabled | Dashboard → pick a workspace → Create New API Key |
| Existing keys | View and revoke only, until June 30, 2026 | Full lifecycle |
| Format | {id}.{secret} | {id}.{secret} — unchanged |
Migrate in three steps
Create a workspace key
In the dashboard, select the workspace that holds the notes your integration uses, then create a key.
Swap the secret
Replace the value of your
TIRO_API_KEY environment variable with the new key. No other code changes are needed.A legacy key reached every note on your account; a workspace key reaches one workspace. If your data spans several workspaces, create one key per workspace.
Security Best Practices
Environment Variables
Store API keys securely using environment variables:Additional Security Guidelines
- Rotate keys regularly: Delete unused keys and generate new ones
- Separate keys per environment: Use different keys for development and production
- Monitor usage: Track API key usage and rotate on anomalies
- Never log API keys: Ensure keys don’t appear in application logs
- Use HTTPS only: Always make requests over secure connections