API keys
An API key serves as a credential to allow an application such as a chat bot to act as a Teamwire client and thus interact with Teamwire users.
Please refer to the Bots SDK documentation and the Administrator Panel documentation for more information about how to create bots and integrate your applications with the Bots SDK.
Manage Teamwire API keys
Create a new API key
POST /v<api_version>/admin/apikeys/
Access restrictions
- Admins and Superadmins must have the allow_modify_api_keys permission.
- Admins can create API keys in their own organisation only.
- Superadmins can create API keys in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
name |
String | No | All admins | The name users will see when an application uses this API key to communicate with them. The word “Bot” will be automatically appended to ensure that users know they’re not talking to a human. |
organisation_id |
Number | Yes | Superadmins | The ID of the organisation to create the API key in. |
comment |
String | Yes | All admins | An optional comment for the API key. It will be visible in the Enterprise API and portal only and is not shown towards users communicating with the application. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the created API key is returned as a JSON object as described for the GET request. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified organisation could not be found. |
| 409 (Conflict) | The request failed because the organisation the API key would belong to has been disabled. |
Return a list of API keys or details about a particular API key
GET /v<api_version>/admin/apikeys/
GET /v<api_version>/admin/apikeys/<apikey_id>/
Access restrictions
- Admins and Superadmins must have the allow_view_api_keys permission.
- Admins can request details of API keys in their own organisation only.
- Superadmins can request details of API keys in any organisation.
- If no apikey_id is specified:
- admins will receive a list of API keys in their own organisation only.
- Superadmins will receive a list of API keys in all organisations.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| apikey_id | Integer | Yes | All admins | The ID of a particular API key for which details should be returned. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. API key information is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the calling admin is not a Superadmin and an API key ID was specified that does not belong to the calling admin’s organisation. |
| 404 (Not Found) | The request failed because the specified API key could not be found. |
| 409 (Conflict) | The request failed because the organisation the API key belongs to has been disabled. |
If an API key ID was specified and the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
id |
String | All admins | The API key’s ID. |
name |
String | All admins | The name users will see when an application uses this API key to communicate with them. The word “Bot” will be automatically appended to ensure that users know they’re not talking to a human. |
comment |
String | All admins | An optional comment for the API key. It will be visible in the Enterprise API and portal only and is not shown towards users communicating with the application. |
state |
String | All admins | The API key’s state, either “Enabled” or “Disabled”. Disabling an API key allows to temporarily suspend access by the applications using the key. |
restrict_visibility |
Boolean | All admins | Either “True” or “False”, indicating whether the visibility of applications using this API key should be limited to certain Teamwire groups. There is a separate endpoint to set these “allowed groups”. |
allowed_groups |
Array | All admins | An array of JSON objects as described below representing the groups allowed to see the application if the restrict_visibility flag has been set. |
appid |
String | All admins | The API key’s App ID. This is the first part of the credentials required by your application to use the client SDK. It should be treated confidentially. |
secret |
String | All admins | The API key’s secret. This is the second part of the credentials required by your application to use the client SDK. It should be treated confidentially. |
organisation_id |
Number | All admins | The ID of the organisation the API key belongs to. |
created_at |
String | All admins | A timestamp indicating when the API key was created. |
updated_at |
String | All admins | A timestamp indicating when the API key was last modified. |
If allowed_groups have been defined, they are returned as an array of JSON objects with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
id |
String | All admins | The group’s ID. |
title |
String | All admins | The group’s title. |
created_at |
String | All admins | A timestamp indicating when the group was created. |
If no API key ID was specified and the request was successful, the JSON structure returned will be an array of JSON objects with elements as described above.
Update an existing API key
PUT /v<api_version>/admin/apikeys/<apikey_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_api_keys permission.
- Admins can update API keys in their own organisation only.
- Superadmins can update API keys in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| apikey_id | Number | No | All admins | The ID of the API key to be updated. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
name |
String | Yes | All admins | The name users will see when an application uses this API key to communicate with them. The word “Bot” will be automatically appended to ensure that users know they’re not talking to a human. |
comment |
String | Yes | All admins | An optional comment for the API key. It will be visible in the Enterprise API and portal only and is not shown towards users communicating with the application. |
state |
String | Yes | All admins | The API key’s state, either “Enabled” or “Disabled”. Disabling an API key allows to temporarily suspend access by the applications using the key. |
restrict_visibility |
String | Yes | All admins | Either “True” or “False”, indicating whether the visibility of applications using this API key should be limited to certain Teamwire groups. There is a separate endpoint to set these “allowed groups”. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The API key has been updated. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the admin is not a Superadmin and an API key ID was specified that does not belong to the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified API key could not be found. |
| 405 (Bad request) | The request failed because no API key was specified. |
| 409 (Conflict) | The request failed because the organisation the API key belongs to has been disabled. |
Delete an API key
DELETE /v<api_version>/admin/apikeys/<apikey_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_api_keys permission.
- Admins can delete API keys in their own organisation only.
- Superadmins can delete API keys in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| apikey_id | Number | No | All admins | The ID of the API key to be deleted. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The API key has been deleted. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the admin is not a Superadmin and an API key ID was specified that does not belong to the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified API key could not be found. |
| 405 (Bad request) | The request failed because no API key was specified. |
| 409 (Conflict) | The request failed because the organisation the API key belongs to has been disabled. |
Manage allowed groups for Teamwire API keys
Add groups to an API key’s “allowed groups” list
POST /v<api_version>/admin/apikeys/<apikey_id>/allowed_groups/
The list of allowed groups determines the visibility of the application(s) using an API key when the “restrict_visibility” flag has been set on the API key.
Access restrictions
- Admins and Superadmins must have the allow_modify_api_keys permission.
- Admins can add groups to the “allowed groups” lists of API keys in their own organisation only.
- Superadmins can add groups to the “allowed groups” lists of API keys in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| apikey_id | Number | No | All admins | The ID of the API key to be modified. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
group_ids |
Array | No | All admins | An array of strings containing the group IDs to be added. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The groups have been added. |
| 400 (Bad request) | The request failed because the list of group IDs contained at least one ID where the group does not exist or does not belong to the admin’s organisation and the admin is not a Superadmin. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the admin is not a Superadmin and an API key ID was specified that does not belong to the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified API key could not be found. |
| 409 (Conflict) | The request failed because the organisation the API key belongs to has been disabled. |
Remove a group from an API key’s “allowed groups” list
DELETE /v<api_version>/admin/apikeys/<apikey_id>/allowed_groups/<group_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_api_keys permission.
- Admins can remove groups from the “allowed groups” lists of API keys in their own organisation only.
- Superadmins can remove groups from the “allowed groups” lists of API keys in any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| apikey_id | Number | No | All admins | The ID of the API key to be modified. |
| group_id | Number | No | All admins | The ID of the group to be removed. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The group has been removed. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the admin is not a Superadmin and an API key ID was specified that does not belong to the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified API key could not be found. |
| 409 (Conflict) | The request failed because the organisation the API key belongs to has been disabled. |