Access Models

Roam supports two access models for API integrations: Organization access and Personal access. These determine what data your integration can see, how messages are sent, and which endpoints are available.

Comparison

	Organization Access	Personal Access
Who it's for	Admins building org-wide bots and automations	Individual users connecting AI tools or personal automations
Principal	App (bot persona)	User (acts as you)
Data scope	All public groups, DMs and private groups the app is added to, and all meetings	Only your data: your meetings, your DMs, your groups
Message identity	App name and icon	Your name and avatar
Auth methods	API Key or OAuth (admin consent)	OAuth or Personal Access Token (user consent)
Webhook scope	All events across the organization	Only events involving you
Token type	Organization token	Personal token

Organization access and Personal access are not a superset/subset relationship. They provide different views of data and different identity semantics.

When to Use Organization Access

Organization access is for integrations that operate at the workspace level, independent of any single user. The integration acts as its own entity with a bot persona.

Common use cases:

• Notification bots -- Post alerts from CI/CD, monitoring, or ticketing systems into Roam groups
• Sales automation -- Trigger messages based on CRM events or deal updates
• Compliance and archival -- Export message archives for legal holds or data warehousing
• User provisioning -- Sync users from Okta, Azure AD, or other identity providers via SCIM
• Post-meeting automation -- Process all meeting transcripts and recordings across the organization

Setup: An admin creates an API client in Roam Administration > Developer and generates an API Key or OAuth credentials. The integration authenticates with an organization token.

When to Use Personal Access

Personal access is for integrations that act on behalf of a specific user. The integration sees exactly what the user sees and sends messages as that user.

Common use cases:

• AI assistants -- Connect Claude, ChatGPT, or other AI tools to search your meetings and messages via MCP
• Personal productivity -- Receive your meeting transcripts and action items for personal follow-up
• Message management -- Search and manage your Roam messages through AI assistants
• Personal automations -- Build workflows triggered by your own activity

Setup: The user authorizes the app via OAuth consent or creates a Personal Access Token. The integration receives a personal token scoped to that user's data.

Admin Policy for Personal Access

Workspace admins control whether Personal access is available. In Roam Administration > Developer, admins can set the policy to one of:

• Disabled -- Personal access is not available. Users cannot authorize apps or create Personal Access Tokens.
• With Approval -- Users can request Personal access, but an admin must approve each request before a token is issued.
• Auto-approve -- Users can authorize apps and create Personal Access Tokens without admin approval.

OAuth App Design

A single OAuth app can support both Organization access and Personal access. The access model is selected at authorization time, not when the app is created.

• One app, two modes -- Your app registration can declare which access models it supports. The mode is chosen per authorization grant.
• Organization access requires admin consent -- only workspace admins can authorize org-wide access.
• Personal access requires user consent -- any user can authorize access to their own data (subject to admin policy).

Endpoint Compatibility

Not every endpoint supports both access models. Most endpoints support Organization access only. The following endpoints additionally support Personal access:

Endpoint	Notes
/token.info	Returns info about the current token
/chat.post	Organization: sends as bot. Personal: sends as you
/chat.history	Personal: only chats you participate in
/transcript.list	Personal: only your meetings
/transcript.info	Personal: only your meetings

Each endpoint's documentation indicates which access models it supports.

Webhooks

All webhook events can be received in both Organization and Personal access modes. The difference is scope:

• Organization: Receives events for all activity across the workspace
• Personal: Receives only events involving the authenticated user

Error Handling

If you call an endpoint that doesn't support your token's access model, the API returns:

{"error": "access_mode_not_supported"}

Check the compatibility table above or each endpoint's documentation to confirm support before making requests.