API Authentication
Overview
To access Medchat services programmatically, you will need your Org ID and scoped API access tokens to call various endpoints in the system. This includes API calls such as get chats, resume chatbot executions, or post SMS messages, among many other available calls.
These artifacts are available under the Medchat Developer portal (Admin > Developer > MedChat Auth) -- for users that have the Developer role.
Pre-existing Authorization Tokens
For Orgs that have generated an API Authorization Token prior to 2/2/23, note that those tokens remain intact and will be displayed as "{Your Org Name} API Client" in the list of Scoped Access Tokens.
Managing Access Tokens
Creating tokens
To create a new token, click on Generate new token under Scoped Access Tokens. The New access token dialog will slide into display, allowing you to set the token name, its optional expiration date, and the scope of access you want to grant for the token.
Available Scopes
The available Scopes that define your Medchat token's access to API calls are as follows:
| Domain | Scope | Token Access | Sample API calls |
|---|---|---|---|
| Live Chats | read.my_orgs.chats | Read chats and chat-related resources | Get chats, Download Chats, Get chat context |
| create.chat_attributes | Create chat attributes | Create Attribute | |
| update.chat_attributes | Update chat attributes | Update attribute | |
| Text (SMS) Chats | read.sms_chats | Read SMS chats | Get SMS chats |
| send.sms_message | Send SMS messages | Post SMS Messages | |
| Widgets | read.widgets | Read widgets and widget-related resources (e.g. topics, stored replies, request forms, etc.) | |
| Chat Bots | impersonate.bot | Read and write messages on behalf of bot, resume bot executions | Resume chatbot execution |
| create.text_bot_executions | Initiate text bot executions for SMS chats | ||
| read.text_bot_executions | Read text bot executions | ||
| Webhooks | create.webhooks | Create webhooks | |
| read.webhooks | Read webhooks | ||
| update.webhooks | Update webhooks and manage webhook secrets | ||
| delete.webhooks | Delete webhooks | ||
| read.webhook_event_categories | Read webhook event categories | ||
| Data Sets | manage.dataset | Create, update, and delete data sets | Create data set |
| get.dataset | Read/query data sets | Get data sets | |
| Users | read.users | Read users (limited scope) | |
| read.my_orgs.users | Read users (full scope) | ||
| read.all.custom_user_attributes | Read users custom attribute values | Get custom user attributes | |
| Custom Reports | read.analytics_query_results | Read/export query results | Execute query |
| Analytics | read.chat_aggregations | Read live chat aggregations | |
| User Verification | create.user_verifyconfig | Create user verification configurations | Create user verification config |
| read.user_verifyconfig | Read user verification configurations | Get user verification config | |
| Registered Chats | create.registered_chats | Create registered chats | Create registered chat |
| read.registered_chats | Read registered chats | Get registered chat | |
| Journeys | create.journey_instances | Create journey instances | |
| Retention Jobs | manage.extractjobs | Create, read, and download extract job results. | Create retention job |
| manage.purgejobs | Create, read, and download extract portion of purge jobs. |
Click Create token to generate your token.
Remember to keep your API Access token secure. It will only be displayed once.
Updating tokens
You currently have the option of updating the name of an existing token from the details panel. Note that once you've created a token, you will not be able to modify its expiration date and scope of access.
If you need to update a token beyond its name, we recommend that you issue a new token with your desired scope and date of expiration, deploy the new token to your relevant applications (i.e. perform key rotation), and then revoke the original token.
Deleting tokens
To delete a token, click on a listed scoped access token to expand the detail panel, and scroll to the bottom. Click on the Delete token button.
Deleting an access token will delete all permissions granted for this token. This action is irreversible.
Updated 6 months ago