Scopes and Permissions

PBXware uses scopes to control access to API resources. A scope is a named permission (e.g. contacts:read, queues:realtime) that grants the right to perform a specific action on a specific resource type. Every API endpoint declares the scope(s) it requires, and a request is only authorized when the presented credentials carry all the required scopes.

How scopes apply

Scopes behave differently depending on the authentication mechanism the caller uses.

User tokens

User Level Tokens are tenant-bound and are automatically granted a fixed set of scopes — the scopes that are necessary for building end-user applications such as gloCOM (e.g. reading contacts, monitoring queues).

The user-level scope set is hard-coded and cannot be customized per-extension. See the User-Level Scopes section below for the full list.

API Keys

API Keys have access for every API resource based on scopes defined for their permission group. For more details about API Keys please check this. See the API-Key Level Scopes section below for the full list.

All scopes

The full scope catalog, grouped by resource.

AI Providers

Scope	Description
`ai:providers:create`	Create new AI provider configurations
`ai:providers:delete`	Delete AI provider configurations
`ai:providers:list`	List all AI providers configured for the organization
`ai:providers:read`	List and view AI provider configurations
`ai:providers:update`	Modify existing AI provider configurations

AI Text-to-Speech

Scope	Description
`ai:tts:read`	View text-to-speech AI provider settings
`ai:tts:update`	Modify text-to-speech AI provider settings

AI Transcriptions

Scope	Description
`ai:transcriptions:read`	View AI call transcription settings
`ai:transcriptions:summary`	Request and retrieve AI-generated call transcription summaries
`ai:transcriptions:update`	Modify AI call transcription settings

AI Voice Agents

Scope	Description
`ai:voice-agents:create`	Create new AI voice agent configurations
`ai:voice-agents:delete`	Delete AI voice agent configurations
`ai:voice-agents:list`	List all AI voice agents in the organization
`ai:voice-agents:read`	List and view AI voice agents and their active session details
`ai:voice-agents:update`	Modify existing AI voice agent configurations
`ai:voice-mcp-servers-status:list`	Fetch AI voice MCP servers status
`ai:voice-mcp-servers-status:read`	Fetch specific AI voice MCP server status
`ai:voice-mcp-servers:create`	Add new MCP server configurations for AI voice agents
`ai:voice-mcp-servers:delete`	Remove MCP server configurations for AI voice agents
`ai:voice-mcp-servers:list`	List all MCP servers configured for AI voice agents
`ai:voice-mcp-servers:read`	List and view MCP server configurations for AI voice agents
`ai:voice-mcp-servers:update`	Modify MCP server configurations for AI voice agents

AI Voicemail

Scope	Description
`ai:voicemail:read`	View AI voicemail transcription settings
`ai:voicemail:update`	Modify AI voicemail transcription settings

Contacts

Scope	Description
`contacts:create`	Create contacts and import contact lists via CSV
`contacts:delete`	Delete contacts and cancel CSV import jobs
`contacts:list`	List and search contacts in the organization
`contacts:read`	Retrieve contact details, activity history, linked records, and CSV export data
`contacts:update`	Modify contacts, merge duplicates, and manage contact links

CRMs

Scope	Description
`crm:app`	Authenticate with CRM integrations and access CRM records, objects, and associations

Departments

Scope	Description
`departments:create`	Create new departments in the organization
`departments:delete`	Delete departments from the organization
`departments:list`	List all departments in the organization
`departments:read`	List and view department details
`departments:update`	Modify department settings

Emergency Button

Scope	Description
`emergency-buttons:read`	View emergency button configurations and compatible extensions
`emergency-buttons:update`	Modify emergency button settings

Enhanced Ring Groups

Scope	Description
`ergs:realtime`	Retrieve real-time data for Enhanced Ring Group resources
`ergs:stats`	Retrieve historical statistics for Enhanced Ring Group resources

Event Publisher

Scope	Description
`event-publisher:create`	Create new webhooks for event notifications
`event-publisher:delete`	Delete event notification webhooks
`event-publisher:list`	List all configured event notification webhooks
`event-publisher:read`	List and view event notification webhook configurations
`event-publisher:update`	Modify event notification webhook settings

Extensions

Scope	Description
`extensions:create`	Create extensions individually or in bulk
`extensions:delete`	Delete extensions from the organization
`extensions:list`	List all extensions in the organization
`extensions:read`	View extension details, assigned DIDs, enhanced services, and department memberships
`extensions:update`	Modify extensions and their enhanced services individually or in bulk

Live Transcriptions

Scope	Description
`live-transcriptions:create`	Create live transcription sessions and link them to channels
`live-transcriptions:delete`	Delete live transcription sessions and remove channel links
`live-transcriptions:list`	List all live transcription sessions
`live-transcriptions:read`	Retrieve live transcription sessions, channel status, and settings
`live-transcriptions:update`	Modify live transcription settings and session channel links

Music On Hold

Scope	Description
`moh:read`	Retrieve the default Music on Hold settings

Queues

Scope	Description
`queues:realtime`	Retrieve real-time data for queue resources
`queues:stats`	Retrieve historical statistics for queue resources

Service Plans

Scope	Description
`service-plans:list`	List available service plans
`service-plans:read`	View available service plan details

SMS

Scope	Description
`sms:messages:send`	Send SMS messages through the organization's SMS trunk

Trunks

Scope	Description
`trunks:list`	List allowed trunks for the organization
`trunks:read`	View allowed trunk details for the organization

UADs

Scope	Description
`uads:list`	List all UADs in the organization
`uads:read`	List UADs and view UAD configurations

User-level scopes

Scopes automatically granted to every Extension user token.

Scope	Description
`ergs:realtime`	Retrieve real-time data for Enhanced Ring Group resources
`queues:realtime`	Retrieve real-time data for queue resources
`queues:stats`	Retrieve historical statistics for queue resources
`ergs:stats`	Retrieve historical statistics for Enhanced Ring Group resources
`contacts:read`	Retrieve contact details, activity history, linked records, and CSV export data
`contacts:list`	List and search contacts in the organization
`contacts:update`	Modify contacts, merge duplicates, and manage contact links
`contacts:create`	Create contacts and import contact lists via CSV
`contacts:delete`	Delete contacts and cancel CSV import jobs
`crm:app`	Authenticate with CRM integrations and access CRM records, objects, and associations
`sms:messages:send`	Send SMS messages through the organization's SMS trunk

How scopes apply​

User tokens​

API Keys​

All scopes​

AI Providers​

AI Text-to-Speech​

AI Transcriptions​

AI Voice Agents​

AI Voicemail​

Contacts​

CRMs​

Departments​

Emergency Button​

Enhanced Ring Groups​

Event Publisher​

Extensions​

Live Transcriptions​

Music On Hold​

Queues​

Service Plans​

SMS​

Trunks​

UADs​

User-level scopes​