Who can use this feature?
System administrator
User administrator
Staff members
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 User API keys provide access to chat and contact related functionality. You can use keys automate your client engagement strategies - automatically create chats with your clients, and place them in the archive until you get a reply, or integrate your other systems to create chats directly on Qwil Messenger. These keys relate to chat-service endpoints.
In order to access your organisation's chat-service endpoints, each request sent must contain a User API Key and its associated Secret as part of the header to be authenticated successfully.
User API Key permissions can be 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.
Note: User API keys can be accessed by all staff users.
Security considerations
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.
Admin users in your organisation can list and delete any keys created by you. If you are an admin user and wish to manage your users' API Keys click.
Note: Your organisation must enable this functionality. If your organisation has not provided access to User API Keys you will see a warning.
To create a User API key:
- From your desktop, click on your profile.
- Click on the User API Keys tab.
- Click on Create New Key.
- Add a name - something that explains what the key will do for example "Create a chat".
- Add CIDR blocks (optional).
- Select the key's permissions (see below).
- Click on Create.
- Important! On the next screen, you will see the User API key ID and Secret. Make sure you copy both. This is the only time you will be able to see the User API Key Secret. If you did not copy the User API key secret you will have to generate new keys.
- Click Done. Your 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-only 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.
To edit a User API key:
Once you've created a User API Key, you can edit its name and permissions at any time.
- From your desktop, click on your profile.
- Click on the User API Keys tab.
- Locate the key your wish to edit.
- Click on the three-dot menu and select Edit.
- A modal will open. Make any necessary changes and click Submit. Your changes will be saved.
To delete a User API key:
It is good practice to delete any User API Keys that is not in use. Please note this action cannot be undone. You can however create new keys with the same permissions at any time.
- From your desktop, click on your profile.
- Click on the User API Keys tab.
- Locate the key your wish to delete.
- Click on the three-dot menu and select Delete.
- A confirmation modal will open. Click Confirm.
- The key will be deleted and can no longer be used.