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.Listing folders from the CLI
tiro folders list and tiro folders tree require OAuth sign-in or an account API key. This is the personal key an integration may ask for. Adding folder:read or all permissions to a workspace or organization system key does not give it a user identity.
- Run
tiro auth statusto check the active credential source.TIRO_TOKENtakes precedence over a saved OAuth login. - For OAuth, remove
TIRO_TOKENfrom the current shell, then runtiro auth login. For an API key, setTIRO_TOKENto an account API key. - Find the workspace GUID with
tiro wiki workspaces, then runtiro folders list --workspace <guid>ortiro folders tree --workspace <guid>.
403 with insufficient_scope means a required permission is missing. For OAuth, sign in again and grant permission that includes folder:read. For an API key, update its permissions or replace the key. folder:write also includes folder:read. The CLI OAuth URL intentionally omits scope: the server derives the allowed scopes from the app and resource for the consent screen. You do not need to add it to the URL yourself.
A 401 with User API key is required for folder access means the operation requires a user identity. Switch to an account API key or OAuth; adding scopes does not resolve this error. If a note query returns no results, check which notes system API keys can access.
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 perform all actions within the resources it can access, 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. This also applies to existing keys. - Scopes apply to every key type (user, workspace, organization).
- Fetch the assignable scope list from
GET /v1/api-key-scopes.
Available scopes
Content editing and reset, including
note_summary:write, are being tested in dev and are not available in production. A write scope does not enable a feature that is disabled in the target environment.Required scope per API
A scoped key may call only the APIs whose scope it holds. Keys without scopes still have key-type and resource-access restrictions.Content editing and reset APIs in dev
Content editing and reset, includingnote_summary:write, are being tested in dev and are not available in production. A write scope does not enable a feature that is disabled in the target environment.
Copy
editState.etag from the read response into the recovery request’s etag. undoAvailable and canReset describe the actions available to that credential for the current content. On 409, read again and review the changes before choosing recovery again. Do not automatically retry Undo with a new etag.
Paragraph Undo reverses one saved change in the selected paragraph and field. Supported fields are transcript, translated, diarized-transcript, and summary. Paragraph summary Undo is available only for new saves that have recoverable history; older saves remain unavailable.
editState.canResetByKind reports note-wide reset availability for original, translated, and summary. This map appears on each paragraph but applies to all paragraphs.
POST /v1/external/notes/{noteGuid}/paragraphs:reset accepts { "kind": "original", "etag": "value from the read response" }. kind is original, translated, or summary. It resets the selected kind across all paragraphs in one operation. original resets both plain and speaker-attributed transcripts, including speaker assignments, while preserving translations and paragraph summaries. translated resets only translations. summary resets only paragraph summaries. Previous Undo history ends for the reset content; other content and its Undo history remain available. Original reset also prevents Undo of affected earlier speaker changes. If any selected content cannot be reset, the whole request fails without partial changes.
The existing single-paragraph reset keeps its behavior: it resets the original transcript, translation, speaker-attributed text, and speaker assignments in one paragraph, while preserving the paragraph summary. Speaker Undo preserves text edits. Note summary and document Undo reverse the latest saved change within that resource. Reset restores the entire summary or document to its generated content and ends its previous Undo history. Document section reset is not available.
Existing edit and restore APIs retain their expectedRevision contract. Other recovery paths above accept POST with { "etag": "value from the read response" }. Successful commands return updated recovery state; read the content again afterward.
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