API Keys
The Tiro API authenticates with API keys. Send your key as a Bearer token in theAuthorization header of every request.
An account API key is tied to a user account and acts with that user’s permissions across every workspace they can currently access. Workspace and organization API keys instead act within the workspace or organization they are tied to.
To connect an internal system with one user consent instead of having each member issue a key, use an OAuth app rather than an API Key. Registration and the token flow are covered in OAuth app integration.
Key types and permissions
Tiro API keys fall into three types, based on who the request represents.
Workspace and organization API keys both run without a user, so we call the two together system API keys. Wherever this documentation says system API key, it means both types.
A workspace API key reaches only the notes inside folders shared with all workspace members. The same scope applies to requests that change a note, such as updating a title, creating a share link, or generating a document. 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 scope. If you need those notes, create and use an account API key instead.
Transition period. Workspace API 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 scope of each key type and how notes outside it appear in responses, see What notes a system API key reads.
If a workspace API 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 limit what a key can do. You choose them when you create the key, and you can change them later.- 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 an account API key from Tiro Platform:1
Sign in
2
Create an account API key
Click Create New API Key, name it, and copy the full key including the dot —
abc123.xR7mK9pL2qW4....3
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.
- Missing Authorization header
- Malformed key (must be
{id}.{secret}) - Unknown key id
- Inactive, expired, or deleted key
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