Skip to main content

API Keys

The Tiro API uses API keys for authentication. Every request carries a valid key in the Authorization 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.
Legacy personal keys are going away. Personal API keys created before workspaces stop working on June 30, 2026. Create a workspace key and swap it in before then — see Legacy personal keys below.

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 write scope includes read for the same resource. For example, a key with only note:write can also call APIs that require note: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:
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.
Keep your API keys secure and never expose them in client-side code. API keys should only be used in server-side applications.

API Key Format

Tiro API keys follow this format:
For example: abc123.xR7mK9pL2qW4...
Common mistake: Do not use just the Key ID (abc123) as your Bearer token. You must use the full key (abc123.xR7mK9pL2qW4...) — the complete string shown when the key was created.

Making Authenticated Requests

Include your API key in the Authorization header of every request:

Authentication Errors

If authentication fails, you’ll receive a 401 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 keys stop working on June 30, 2026. After that, requests made with one return 401 Unauthorized. Migrate before then to avoid downtime.
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