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 System API keys are geared towards automating and simplifying the administration of your organisation, such as managing users, client teams, invitations, and exporting your organisation's data. System API keys relate to entity-service endpoints.
In order to access your organisation's entity-service endpoints each request sent must contain a System API Key and its associated Secret as part of the header to be authenticated successfully.
System 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.
Security considerations
System 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 System API key:
- From your desktop, click on the admin menu.
- Click on System API Keys.
- Click on Create.
- Add a name - something that explains what the key will do for example "Log a chat in Salesforce".
- Add CIDR blocks (optional)
- Select the key's permissions (see below).
- Click on Create.
-
Important! On the next screen, you will see the System API key ID and Secret. Make sure you copy both. This is the only time you will be able to see the System API Key Secret. If you did not copy the System API key secret you will have to generate new keys.
- Click Done. Your System 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 export data - It allows you to export all of your organisation's user records as well as all of the chat records and metadata (excluding attachments) that have taken place in your organisation.
- This key can perform read-only admin actions - It allows you to use the GET method to request information, such as user details (UUID, identifier, email), user's avatars, list of all users, client teams, and client team memberships.
- This key can perform write-only admin actions - It allows you to use the POST method to send data to a server to create or update resources in your organisation. With this permission you can create, edit, and deactivate users, manage invitations, manage user permissions, as well as create, edit and deactivate client teams and client team memberships.
Note: To see an example of how you can use System API Keys see Send automated messages via the Butler.
To edit a System API key:
Once you've created a System API Key, you can edit its name and permissions at any time.
- From your desktop, click on the admin menu.
- Click on System API Keys.
- Locate the key your wish to edit.
- Select the three button menu next to it and click edit.
- A modal will open. Make any necessary changes and click Save. Your changes will be saved.
To delete a System API key:
It is good practice to delete any System 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.
- From your desktop, click on the admin menu.
- Click on System API Keys.
- Locate the key your wish to delete.
- Click on the three dot menu next to it and click delete.
- A confirmation modal will open. Click Delete.
- The key will be deleted and can no longer be used.