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.
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.

​
Getting Your API Key

Create your key from the Tiro Platform dashboard:
1

Sign in

Go to platform.tiro.ooo/dashboard/api-keys.
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: 
{id}.{secret}
For example: abc123.xR7mK9pL2qW4...
PartExampleDescription
Key ID ({id})abc123Visible 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 Keyabc123.xR7mK9pL2qW4...The entire string including the dot. This is what you use as the Bearer token.
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: 
curl -H "Authorization: Bearer $TIRO_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.tiro.ooo/v1/external/notes

​
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
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid",
    "type": "authentication_error"
  }
}

​
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.
Legacy personal keyWorkspace key
ScopeAccount-wideOne workspace
Create newDisabledDashboard → pick a workspace → Create New API Key
Existing keysView and revoke only, until June 30, 2026Full lifecycle
Format{id}.{secret}{id}.{secret} — unchanged
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: 
# .env file (never commit this!)
TIRO_API_KEY=abc123.XYZ...

​
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