OAuth Scopes and Endpoints
Required Scopes and Endpoint Domains for Talkdesk
When integrating with Talkdesk, your application needs specific permissions to interact with the API.These permissions are defined by access scopes, which determine what data your application can access and what actions it can perform.
This topic provides information about the required access scopes and endpoint domains for the Talkdesk provider.
Understanding Scopes
Scopes are a way to limit an application's access to a user's data. They define the specific actions that an application can perform on behalf of the user.
For example, a read-only scope might allow an application to view data, while a full access scope might allow it to modify data.
Required Scopes for Talkdesk
The provider accesses Talkdesk data on a read-only basis, so the custom OAuth application you register must be granted read access to the resources you intend to query. You select these scopes when you create the application (see Creating a Custom OAuth Application).
Add the scopes that correspond to the data you want to access. If the application is missing a scope that a queried table requires, the Talkdesk token request or the query fails.
The following table lists the minimal scope required by each view and stored procedure. The scope names match the values shown in the Talkdesk OAuth Clients screen when you add scopes to the application.
| Entity | Statement Types | Minimal Required Scopes |
| Users | SELECT | users:read |
| Teams | SELECT | industries-scheduler-teams:read |
| Queues | SELECT | queues:read |
| UserQueues | SELECT | queues-users:read |
| Contacts | SELECT | contacts:read |
| ContactIntegrations | SELECT | contacts-integrations:read |
| Cases | SELECT | cases-public:read |
| CaseFields | SELECT | case-fields-public:read |
| Callbacks | SELECT | schedule-callbacks:read |
| Campaigns | SELECT | campaigns:read |
| CampaignUsers | SELECT | campaigns:read |
| CampaignRecordLists | SELECT | campaigns:read |
| CampaignDoNotCallLists | SELECT | campaigns:read |
| RecordLists | SELECT | record-lists:manage |
| RecordListRecords | SELECT | record-lists:manage |
| DoNotCallLists | SELECT | do-not-call-lists:manage |
| DoNotCallEntries | SELECT | do-not-call-lists:manage |
| Attributes | SELECT | attributes:read |
| AttributeCategories | SELECT | attributes:read |
| AttributeUsers | SELECT | attributes:read |
| Prompts | SELECT | prompts:read |
| PromptFlows | SELECT | prompts:read |
| PromptsUsage | SELECT | prompts:read |
| Account | SELECT | account:read |
| BillingAccounts | SELECT | express-accounts:read |
| Invoices | SELECT | express-accounts-invoices:read |
| Products | SELECT | express-products:read |
| Subscriptions | SELECT | express-accounts-subscriptions:read |
| Wallets | SELECT | account-wallets:read |
| MonthlyUsage | SELECT | express-accounts-usage:read |
| BucketConfigurations | SELECT | bucket-configurations:read |
| GuardianUsers | SELECT | guardian-users:read |
| GuardianUserRoles | SELECT | guardian-users:read |
| GuardianSessionLogs | SELECT | guardian-sessions:read |
| GuardianCases | SELECT | guardian-cases:read |
| GuardianCallsQuality | SELECT | guardian-call-quality:read |
| ScimUsers | SELECT | scim |
| ResourceTypes | SELECT | scim |
| GetCallRecordings | EXECUTE | recordings:read |
| DownloadPromptAudioFile | EXECUTE | prompts:download |
Report views: Every view whose name ends in Report (for example, CallsReport) requires both data-reports:read and data-reports:write. The provider needs write access because each report query first creates a temporary report job and then reads its results.
For the authoritative, most up-to-date scope required by each endpoint, refer to the Talkdesk API documentation.
Understanding Endpoint Domains
Endpoint domains are the specific URLs that the application needs to communicate with in order to authenticate, retrieve records, and perform other essential operations.
Allowlisting these domains ensures that the network traffic between your application and the API is not blocked by firewalls or security settings.
Note: Most users do not need to make any special configurations. Allowlisting is typically only necessary for environments with strict security measures, such as restricted outbound network traffic.
Required Endpoint Domains for Talkdesk
| Domain | Always Required | Description |
| talkdeskid.com | True | The Talkdesk identity domain the provider uses to obtain and refresh OAuth access tokens. The exact domain depends on your Region (see the region-specific table below). |
| talkdeskapp.com | True | The Talkdesk API domain the provider uses to retrieve data. The exact domain depends on your Region (see the region-specific table below). |
Region-Specific Domains
Some providers use different domain suffixes or URLs based on the region where their services are hosted.
This regional segmentation helps improve performance, assists with regional data regulations compliance, and ensures better service availability.
When setting up the connection properties for your application, it's important to specify the appropriate region. The following table lists the placeholders for different regions:
| Region | Authentication Domain | API Domain |
| US (default) | talkdeskid.com | api.talkdeskapp.com |
| EU | talkdeskid.eu | api.talkdeskapp.eu |
| CA | talkdeskidca.com | api.talkdeskappca.com |
| AU | talkdeskid.au | api.mytalkdesk.au |
| UK | talkdeskid.co.uk | api.talkdeskapp.co.uk |
| FedRamp | talkdeskid-pubsec.com | api.talkdeskapp-pubsec.com |