Choose an authentication method

OAuth tokens and account API keys act with a user’s permissions. Workspace and organization API keys belong to the workspace or organization. Newly issued system keys can see notes in folders shared with all workspace members. Check the scope of each older key, since some have different access.

Which credential should I use?

How do scopes and note access differ?

Scopes such as note:read and folder:write determine which actions a credential can perform. The credential type determines which notes and folders it can access. A newly issued workspace API key with note:read still cannot read a private folder. An API key without explicit scopes has no scope-based action restriction. Its credential type still limits note access. OAuth requires granted scopes. See API authentication and MCP setup for the per-operation scopes.

Why can’t system API keys read private folders?

New workspace and organization API keys work with notes in folders shared with all workspace members. Private folders, folders shared with selected members, and directly shared notes remain outside that scope. Older system keys may differ. For private notes, use an OAuth token or account API key belonging to a user who can access them. See What notes a system API key reads.

Which requests require an API key?

• Organization administration (members, workspaces and sessions), voice file jobs, and realtime transcription scopes require an API key.
• Use an API key for server-to-server access without a user. Tiro does not offer the client_credentials grant or act as an OpenID Connect identity provider.
• Creating a realtime transcription session requires a workspace API key or an account API key bound to a workspace. An unbound account key or an organization key receives 403 workspace_bound_key_required.

Why does realtime transcription use a separate token?

Your server creates the session with a workspace API key or a workspace-bound account API key. The response includes wsUrl and streamToken. Pass the session token to the audio client so it can connect without receiving the API key. The token is returned only when you create the session. See the realtime transcription overview.

How do I connect my own MCP client?

1. Read https://mcp.tiro.ooo/.well-known/oauth-protected-resource/mcp to find the authorization server, https://api.tiro.ooo.
2. Read https://api.tiro.ooo/.well-known/oauth-authorization-server for the endpoints and supported methods.
3. Use the advertised registration_endpoint to register the client (RFC 7591) and get a client_id.
4. Request user consent with Authorization Code and PKCE S256. Include resource=https://mcp.tiro.ooo/mcp.
5. Exchange the code for a token and send it with MCP requests as Authorization: Bearer <access_token>.

For redirect_uris, use HTTPS, HTTP on localhost, 127.0.0.1 or [::1], or the cursor scheme. Include authorization_code in grant_types. Include refresh_token if the client needs refresh tokens. Supported token_endpoint_auth_method values are none, client_secret_basic, and client_secret_post. If you omit scope at registration, the client can request any delegable MCP scope. Each connection requires user consent, and the token carries the scopes that the user grants. MCP and REST tokens are issued for different resources. Use a REST token for /v1/external/**.