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:demand	Request and retrieve on-demand call transcription status
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

Calls

Scope	Description
calls:manage	Manage calls (initiate, hangup, transfer etc.)
calls:read	Retrieve a list of calls

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

Dial Groups

Scope	Description
dial-groups:create	Create new dial groups in the organization
dial-groups:delete	Delete dial groups from the organization
dial-groups:list	List all dial groups in the organization
dial-groups:read	List and view dial group details
dial-groups:update	Modify dial group settings

DIDs

Scope	Description
dids:read	Retrieve DID details
dids:update	Update a DID

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:read	Retrieve ERG details
ergs:realtime	Retrieve real-time data for Enhanced Ring Group resources
ergs:stats	Retrieve historical statistics for Enhanced Ring Group resources
ergs:update	Update an ERG

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:balance:credit	Credit an amount to the balance of a main extension
extensions:balance:debit	Debit an amount from the balance of a main extension
extensions:balance:read	View the current balance for a main extension
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

Greetings

Scope	Description
files:list	Retrieve a list of sound files

IVRs

Scope	Description
ivrs:read	Retrieve IVR details
ivrs:update	Update an IVR

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:read	Retrieve Queue details
queues:realtime	Retrieve real-time data for queue resources
queues:stats	Retrieve historical statistics for queue resources
queues:update	Update a Queue

Reports

Scope	Description
reports:read	Retrieve reporting data across configuration 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
sms:numbers:create	Create SMS numbers individually or in bulk
sms:numbers:delete	Delete an SMS number
sms:numbers:list	Retrieve a list of SMS numbers
sms:numbers:read	Retrieve SMS number configuration
sms:numbers:update	Modify SMS numbers configuration individually or in bulk

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
calls:manage	Manage calls (initiate, hangup, transfer etc.)
calls:read	Retrieve a list of calls