Skip to main content

Understanding Master API Keys

  • Updated

Who can use this feature?

System administrators only

 

Our API keys provide access to read, write, and update many types of data in Qwil Messenger, allowing you to integrate Qwil with third-party applications.

Qwil's Master User API keys provide access to chat and contact related functionality. You can use the Chat Butler to send organisation-wide messages, automate your client engagement strategies, or integrate your other systems to create chats directly on Qwil Messenger. Additionally, with Master User API Keys you can send messages on behalf of any user. These keys relate to chat-service endpoints.  

In order to access your organisation's chat-service endpoints, each request sent must contain a Master User API Key and its associated Secret as part of the header to be authenticated successfully. Typically, the header will also require an "on-behalf-of" entry for the user who is performing the action.

Master API Key permissions are controlled and usage can be further restricted using CIDR. CIDR restricts the IP addresses from which the API request can originate. You can also specify a CIDR range - rather than specific individualised IP addresses. 

 

Security considerations

Master User API Keys are very powerful and you should treat them as you would a password. It is best practice to revoke them if they are not being used and allow the fewest permissions possible. 

 

To create a Master User API key:

  1. From your desktop, click on the admin menu.
  2. Click on Master User API Keys.


  3. Click on Create.
  4. Add a name - something that explains what the key will do for example "Create a chat".
  5. Add CIDR blocks (optional)
  6. Select the key's permissions (see below).

    Screenshot_2023-05-11_at_14.48.39.png
  7. Click on Create.
  8. Important! On the next screen, you will see the Master User API key ID and Secret. Make sure you copy both. This is the only time you will be able to see the Master User API Key Secret. If you did not copy the Master User API key secret you will have to generate new keys.

    Screenshot_2020-08-10_at_15.09.50.png
  9. Click Done. Your Master User API Key will be created.

What is each permission for?

Each checkbox provides different permissions for the key to access endpoints and make requests via the API:

  • This key can perform read-only chat actions - It allows you to use the GET method to request information, such as membership details of a user, a chat thread and its participant details, or the content of messages in a chat from one sequence number to another (including system messages).
  • This key can perform write-only chat actions - It allows you to use the POST method to send data to a server to create or update chats in your organisation. With this permission, you can create a new chat with a title and participants, rename a chat, add participants, send messages and attachments, or send messages via the butler.
  • This key can export data - It allows you to export chat records and metadata (excluding attachments) that have taken place in your organisation.
  • This key can perform read/write contact actions - It allows you to use the GET method to request information, such as a list of contacts or lookup a specific contact by uuid, identifier, or email. You can also perform write actions like invite client or staff if you are an admin user.

Note: To see an example of how you can use System API Keys see Send automated messages via the Butler.

 

To edit a Master User API key:

Once you've created a Master User API Key, you can edit its name and permissions at any time.

  1. From your desktop, click on the admin menu.
  2. Click on Master User API Keys.
  3. Locate the key your wish to edit.
  4. Select the three dot menu and click Edit.

    Screenshot_2020-08-10_at_12.06.37.png
  5. A modal will open. Make any necessary changes and click save. Your changes will be saved.

 

To delete a Master User API key:

It is good practice to delete any Master User API Keys that are not in use. Please note this action cannot be undone. You can however create new keys with the same permissions at any time. 

  1. From your desktop, click on the admin menu.
  2. Click on Master User API Keys.
  3. Locate the key your wish to delete.
  4. Select the three-dot menu and click Delete.

    Screenshot_2020-08-10_at_12.07.13.png
  5. A confirmation modal will open. Click delete.
  6. The key will be deleted and can no longer be used.

 

Integration examples

Here are some examples of how you can use Master User API Keys:

Related articles