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.
A workspace system key reads only the notes inside folders shared with all workspace members. Notes in a private folder, notes in a folder shared with only some members, and notes that sit in no folder at all are outside that read scope. If you need those notes, or you need to create, update, or delete data outside the Voice File Job lifecycle, create and use a user key instead.
Transition period. Workspace system keys created before this read scope took effect keep their previous behavior for now, and are being moved over in stages. A key you create today can therefore return fewer notes than an older key, which is expected. For the read scope of each key type and how notes outside it appear in responses, see What notes a system key reads.
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.Scopes
Scopes narrow what a key can do — a least-privilege setting. You choose them at issuance, and you can change them afterward.- A key with no scopes can do everything, including APIs added later. Specify the scopes a key needs if you require least-privilege access. Scopes narrow access rather than grant it — a scoped key can only call the APIs covered by its scopes; anything else is rejected with
403 insufficient_scope. - A
writescope includesreadfor the same resource. For example, a key with onlynote:writecan also call APIs that requirenote:read. - Scopes apply to every key type (user, workspace, organization).
- Fetch the assignable scope list from
GET /v1/api-key-scopes.
Available scopes
Required scope per API
A scoped key may call only the APIs whose scope it holds. A key with no scopes may call every API.Getting Your API Key
Create your key from the Tiro Platform dashboard:1
Sign in
2
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.
3
Create a key
Click Create New API Key, name it, and copy the full key including the dot —
abc123.xR7mK9pL2qW4....4
Store it
Save it as an environment variable. The secret is shown once and can’t be recovered after you close the dialog.
API Key Format
Tiro API keys follow this format:abc123.xR7mK9pL2qW4...
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.
The format is identical, so migrating is a one-line swap — no code rewrite.
Migrate in three steps
1
Create a workspace key
In the dashboard, select the workspace that holds the notes your integration uses, then create a key.
2
Swap the secret
Replace the value of your
TIRO_API_KEY environment variable with the new key. No other code changes are needed.3
Revoke the legacy key
Once traffic runs on the new key, delete the legacy key from the Legacy personal keys section of the dashboard.
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