Build consent-based integrations with OAuth

With an OAuth app, your internal portal can read a member’s notes on their behalf without each member issuing an API key. The member signs in to Tiro and passes a consent screen once, and the app then acts only within the permissions that member already has.

When should you use an OAuth app?

Situation	Recommended approach
An internal portal or collaboration tool shows the notes of the signed-in member	OAuth app (this page)
A batch job or provisioning script handles organization data with no user present	Organization API key
An individual works with their own notes in their own tooling	Account API key

OAuth apps support the Authorization Code flow only, and PKCE is required. There is no client_credentials flow for obtaining a token without a user, so use an API key for server-to-server integrations.

Step 1. Register an OAuth app

Organization apps are registered by an organization Admin or Developer, and workspace apps by a workspace Admin, at Tiro Platform.

Open the OAuth apps screen

In the Tiro Platform side menu, open the [OAuth apps] menu for your organization or workspace and press [Register OAuth app].

Enter the app details

Enter the app name, the Redirect URI, and the scopes the app will request from users. The Redirect URI must start with https://, and it won’t register if the URL carries user info or a fragment after #. It has to match the URL you return to after authorization character for character, and it can’t be edited after registration, so register a new app if the URL changes.

Store the Client ID and Client Secret

Right after registration, the screen shows the Client ID and Client Secret. The Client Secret is shown this one time and can’t be retrieved again. Store it somewhere safe, such as a server environment variable, right away.

http://localhost can’t be registered as a Redirect URI. For local development, register an HTTPS tunnel or a development domain as the Redirect URI and let that address forward the callback to your machine.

The OAuth app registration screen is rolling out gradually. If you don’t see the menu, ask your account manager or partners@theplato.io and we’ll issue an app for you.

Once you close the registration screen, the Client Secret can’t be viewed anywhere again. If you lose it, register a new app or ask your account manager to reissue it. Discarding an app also disconnects every user connection made through it.

Scopes you can request

An OAuth app can request only the permissions a user is able to delegate. Organization management scopes (organization_member:*, workspace:*, session:write) can’t be delegated and are available to organization API keys only.

Scope	What the app can do
`note:read`	Read note lists, metadata, and transcripts
`note:write`	Update note metadata such as titles. Includes `note:read`
`note_summary:read`	Read note summaries (one-page documents)
`note_document:read`	Read generated documents
`note_document_template:read`	List and read document templates
`folder:read`	Read folders
`folder:write`	Create, update, and delete folders. Includes `folder:read`
`wiki:read`	Read and search Wiki
`word_memory:read`	Read word memory

What the app actually reaches is the overlap between the scopes the user consented to and the permissions that user holds in Tiro. Workspaces and notes the user can’t see stay out of reach no matter which scopes were granted. Send the user from your app to the Tiro authorization page. First generate a random code_verifier, then hash that string as UTF-8 bytes with SHA-256 and send the unpadded Base64URL encoding of the digest as code_challenge. Sending a hex string or the raw digest bytes gets rejected at the token exchange step.

GET https://api.tiro.ooo/v1/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://portal.example.com/tiro/callback
  &scope=note:read%20note_summary:read
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https://api.tiro.ooo

Parameter	Description
`response_type`	Always `code`
`client_id`	The Client ID of the registered app
`redirect_uri`	Exactly the same value as the registered Redirect URI
`scope`	A space-separated list of scopes. You can request only a subset of the scopes registered on the app; omit it to request all of them
`state`	An unpredictable random string. The same value comes back on the callback
`code_challenge`, `code_challenge_method`	PKCE values. Only `S256` is supported
`resource`	The target the token is used against. For the External API this is `https://api.tiro.ooo`

After the user signs in with their Tiro account, reviews the app name and requested scopes on the consent screen, and approves, code and state come back to your Redirect URI.

https://portal.example.com/tiro/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE

Validate state on the callback

Check state before you exchange the token. Store the value you generated for the authorize request in the user’s session, compare it with the value that comes back on the callback, then clear the stored value. If it’s missing or different, stop the request right there. Skipping this check allows login CSRF: an authorization the attacker started gets attached to the victim’s session, connecting them to an account they know nothing about.

Members of organizations using SSO sign in through their corporate IdP as usual before the consent screen. The consent screen is scoped to that member’s Tiro account, and the app receives that account’s permissions only.

Step 3. Exchange the code for a token

Turn the validated code into an access token from your server. Handle the Client Secret on the server only and never put it in browser or app code. An authorization code works exactly once, so sending it twice is rejected with invalid_grant.

curl -X POST https://api.tiro.ooo/v1/oauth/token \
  -u "$TIRO_CLIENT_ID:$TIRO_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$AUTHORIZATION_CODE" \
  -d redirect_uri="https://portal.example.com/tiro/callback" \
  -d code_verifier="$CODE_VERIFIER" \
  -d resource="https://api.tiro.ooo"

const credentials = Buffer.from(
  process.env.TIRO_CLIENT_ID + ":" + process.env.TIRO_CLIENT_SECRET
).toString("base64");

const response = await fetch("https://api.tiro.ooo/v1/oauth/token", {
  method: "POST",
  headers: {
    Authorization: "Basic " + credentials,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: authorizationCode,
    redirect_uri: "https://portal.example.com/tiro/callback",
    code_verifier: codeVerifier,
    resource: "https://api.tiro.ooo",
  }),
});

const token = await response.json();

import os
import requests

response = requests.post(
    "https://api.tiro.ooo/v1/oauth/token",
    auth=(os.environ["TIRO_CLIENT_ID"], os.environ["TIRO_CLIENT_SECRET"]),
    data={
        "grant_type": "authorization_code",
        "code": authorization_code,
        "redirect_uri": "https://portal.example.com/tiro/callback",
        "code_verifier": code_verifier,
        "resource": "https://api.tiro.ooo",
    },
)

token = response.json()

form := url.Values{}
form.Set("grant_type", "authorization_code")
form.Set("code", authorizationCode)
form.Set("redirect_uri", "https://portal.example.com/tiro/callback")
form.Set("code_verifier", codeVerifier)
form.Set("resource", "https://api.tiro.ooo")

req, err := http.NewRequest(
    "POST",
    "https://api.tiro.ooo/v1/oauth/token",
    strings.NewReader(form.Encode()),
)
if err != nil {
    return err
}
req.SetBasicAuth(os.Getenv("TIRO_CLIENT_ID"), os.Getenv("TIRO_CLIENT_SECRET"))
req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

resp, err := http.DefaultClient.Do(req)

val form = LinkedMultiValueMap<String, String>()
form.add("grant_type", "authorization_code")
form.add("code", authorizationCode)
form.add("redirect_uri", "https://portal.example.com/tiro/callback")
form.add("code_verifier", codeVerifier)
form.add("resource", "https://api.tiro.ooo")

val token = RestClient.create()
    .post()
    .uri("https://api.tiro.ooo/v1/oauth/token")
    .headers { headers -> headers.setBasicAuth(clientId, clientSecret) }
    .body(form)
    .retrieve()
    .body(TokenResponse::class.java)

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "note:read note_summary:read"
}

Client authentication works with both HTTP Basic and body parameters (client_id, client_secret).

expires_in is the remaining lifetime in seconds and varies with the app’s configuration. Don’t hardcode the value; use whatever comes back in the response. Apps that also receive a refresh_token should follow the refresh procedure below, and apps that don’t can send the user back to the authorization page before the token expires.

Step 4. Call the API

Put the access token in the Authorization header exactly as you would an API key. The endpoints you can call and the response formats match what’s covered in the API Overview.

curl https://api.tiro.ooo/v1/external/notes \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The notes in the response are the ones the consenting user can see in the app. It’s the same result as calling with that user’s account API key.

Step 5. Refresh the token

If the token exchange response includes a refresh_token, you can get a new access token without asking the user to consent again.

curl -X POST https://api.tiro.ooo/v1/oauth/token \
  -u "$TIRO_CLIENT_ID:$TIRO_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

const response = await fetch("https://api.tiro.ooo/v1/oauth/token", {
  method: "POST",
  headers: {
    Authorization: "Basic " + credentials,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token: refreshToken,
  }),
});

const token = await response.json();

response = requests.post(
    "https://api.tiro.ooo/v1/oauth/token",
    auth=(os.environ["TIRO_CLIENT_ID"], os.environ["TIRO_CLIENT_SECRET"]),
    data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
    },
)

token = response.json()

A refresh token works exactly once. When the response carries a new refresh token, discard the previous value and store the new one.
Sending a refresh token that was already used is treated as theft, and every token on that user connection is invalidated. You then have to ask the user to consent again.
A connection left unrefreshed for a long time expires. Each refresh pushes the expiry further out, so connections in steady use stay alive.
Refreshes are rejected once the app has been discarded or the user has disconnected it.

If a network problem leaves you without a response to a refresh request, don’t send the same refresh token again. The server may have already rotated it. Clearing the stored token and prompting the user to reauthorize is the safer move.

Disconnect

When a user stops using the app, revoke the refresh token to disconnect. Access tokens already issued expire on their own once expires_in passes.

curl -X POST https://api.tiro.ooo/v1/oauth/revoke \
  -u "$TIRO_CLIENT_ID:$TIRO_CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN"

await fetch("https://api.tiro.ooo/v1/oauth/revoke", {
  method: "POST",
  headers: {
    Authorization: "Basic " + credentials,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ token: refreshToken }),
});

requests.post(
    "https://api.tiro.ooo/v1/oauth/revoke",
    auth=(os.environ["TIRO_CLIENT_ID"], os.environ["TIRO_CLIENT_SECRET"]),
    data={"token": refresh_token},
)

Server metadata

The endpoints and supported methods are published in the standard metadata document.

GET https://api.tiro.ooo/.well-known/oauth-authorization-server

Common errors

Error	Cause and fix
authorize returns 400	The Redirect URI differs from the registered value. A trailing slash or a query string counts as a mismatch.
Token exchange returns `invalid_grant`	The authorization code was already used or has expired. Send the user back to the authorization page. The same error appears when `code_verifier` doesn’t match `code_challenge`.
Token exchange returns `invalid_client`	The Client ID or Secret is wrong. A discarded app gives the same result.
authorize returns `invalid_scope`	You requested a scope that isn’t registered on the app. Only a subset of the registered scopes can be requested.
An API call returns `403 insufficient_scope`	The consented scopes don’t cover this API. Check which scope it needs in Authentication.

Related pages: Authentication · Integrate at the organization level · API Overview

Home

Getting Started

API

Voice File

Webhooks

MCP

CLI

Developer Resources

Build consent-based integrations with OAuth

When should you use an OAuth app?

Step 1. Register an OAuth app

Scopes you can request

Validate state on the callback

Step 3. Exchange the code for a token

Step 4. Call the API

Step 5. Refresh the token

Disconnect

Server metadata

Common errors

​When should you use an OAuth app?

​Step 1. Register an OAuth app

​Scopes you can request

​Step 2. Get user consent

​Validate state on the callback

​Step 3. Exchange the code for a token

​Step 4. Call the API

​Step 5. Refresh the token

​Disconnect

​Server metadata

​Common errors

When should you use an OAuth app?

Step 1. Register an OAuth app

Scopes you can request

Step 2. Get user consent

Validate state on the callback

Step 3. Exchange the code for a token

Step 4. Call the API

Step 5. Refresh the token

Disconnect

Server metadata

Common errors