Skip to main content
An organization API key is a server-to-server key for managing the notes, members, and sessions of the workspaces in your organization. Authentication and webhooks work the same as a regular API key; only the access scope differs.
Only organization admins can issue organization API keys and register organization webhooks.

​
How far does an organization API key reach?

An organization API key reaches the notes inside workspaces that belong to the organization. It doesn’t reach notes in personal workspaces outside the organization. An organization API key is a system API key, so even inside those workspaces it reads only notes in folders shared with all members. Notes in a member’s private folder, notes in a folder shared with only some members, and notes that sit in no folder at all are outside its read scope. For the full read scope, see What notes a system API key reads.

​
Endpoints you can call with an organization API key

Use these endpoints to manage the organization, its workspaces, member access, and notes.

​
Manage workspaces programmatically

An organization API key lets you create, update, and delete workspaces. Use it from an internal provisioning tool or an automation script.
  • List and read: Sweep the organization’s workspaces with GET .../workspaces. Search names with query and page through with cursor and size.
  • Create, update, delete: Create a new workspace with POST, change its name or description with PATCH .../{workspaceGuid}, and clean up with DELETE. For updates, list only the fields you want to change in the updateMask query parameter. For example, ?updateMask=name changes the name and leaves everything else as is.
  • Set usage quotas: Set a per-workspace recording quota with quotaInMinutes on PATCH .../{workspaceGuid}/quota. null means unlimited, 0 blocks recording entirely, and a positive number grants that many minutes. If an organization-level quota is set, the sum of workspace quotas can’t exceed it.
Reads require the workspace:read scope; creating, renaming, setting quotas, and deleting require workspace:write. A key issued without scopes is allowed to do everything. See Authentication for details.

​
Manage member access

Use GET .../members to find users who already belong to the organization, then assign a workspace and role with PUT .../workspaces/{workspaceGuid}/members/{userGuid}. Repeating the same PUT leaves the same final state. Use DELETE to remove the assignment. Choose ADMIN, MEMBER, or VIEWER. ADMIN can manage the workspace; ADMIN and MEMBER consume a seat and can record. VIEWER is read-only, consumes no seat, and cannot record. If no seat remains, assigning ADMIN or MEMBER returns 409. Suspend recording with PUT .../recording-suspension and resume it with DELETE on the same path. DELETE .../sessions revokes every current Tiro session, but it does not prevent the user from signing in again. To block future access, also remove access in your identity provider, such as Entra ID. Member reads require organization_member:read; recording and workspace assignment changes require organization_member:write; session revocation requires session:write. These APIs do not create or invite users, reset passwords, or delete accounts.
An organization key can access every member’s notes, names, and email addresses and can forcibly revoke member sessions, so store it carefully and control who can use it. If you suspect it leaked, revoke it in the organization console and reissue it immediately. A key’s secret is shown only at issue time.

​
Next steps

Authentication

Access scope and issuance for each API key type

Webhooks overview

Event structure, retry policy, and verification