Scopes and permissions
Four settings on the application decide what an installation can do. The Gateway checks all of them on every request.
| Setting | Decides |
|---|---|
| Scopes | Which operations the installation can call |
| Data access flags | Which sensitive data those operations may return |
| Restrictions | Which channels, teams or subsites conversation reads cover |
| Author mappings | Which native operator a write is attributed to |
Scopes
Section titled “Scopes”Grant the smallest set the integration needs. Each operation in the reference lists its exact scopes, and the scope reference describes all 19.
Common starting points:
| Task | Scopes | Data access flags |
|---|---|---|
| Explore what’s available | website_read |
none |
| Read conversation metadata | website_read, conversation_read |
none |
| Read transcripts | website_read, conversation_read, message_content_read, contact_read_pii |
message_content, pii |
| Look up contacts | website_read, contact_read, plus contact_read_pii for names and emails |
pii for personal fields |
| Report on AI-handled conversations | website_read, reports_read, conversation_read |
none, or message_content and pii for content-based measures |
| Review AI feature configuration | website_read, config_read |
none |
| Follow change events | website_read, event_read |
none |
Data access flags
Section titled “Data access flags”Scopes say which operations an app can call. Data access flags say which sensitive data it can receive. Both are required.
| Flag | Covers |
|---|---|
message_content |
Message text, subjects and note content |
pii |
Personal information about contacts and visitors. Requires the contact_read_pii scope. |
internal_notes |
Internal notes and internal operator messages |
Projections
Section titled “Projections”Some fields only appear when the extra permission is present. For example, a contact’s name, email, mobile and phone need contact_read_pii and the pii flag. Without them, a contact contains only id, blocked and access.pii: false.
Some measures in the AI conversation summary need content and PII access. Without it they are null, never a made-up zero.
Conditional parameters
Section titled “Conditional parameters”Some filters need more permission than the base operation. For example, query on GET /api/v1/conversations also needs message_content_read and contact_read_pii. The Gateway rejects the request before reading any data. The reference lists these in each operation’s notes.
Restrictions
Section titled “Restrictions”An application can be limited to specific channel_ids, team_ids or subsite_ids. Conversation reads and the AI conversation summary apply these filters before paging or aggregating. An empty list denies every row in that dimension.
Operations that can’t apply these filters are unavailable to a restricted installation. These include contacts, notes, configuration, AI features and event subscriptions.
Author mappings
Section titled “Author mappings”Visitor note and disposition writes are attributed to a native INSIDE operator. Set the application’s author mappings to a JSON object from website ID to native operator ID:
{ "web_4927_123": 1042 }A mapping only controls attribution. It doesn’t give the application that operator’s permissions.
Security recommendations
Section titled “Security recommendations”- Create a separate application or credential for each integration and each AI agent.
- Grant read-only scopes unless writes are needed.
- Enable
pii,message_contentandinternal_notesonly when required. - Use short credential expiries and rotate them regularly.
- If a token leaks, revoke or rotate the credential straight away.