Connectors
A Teamwire connector represents a specific communication channel used by a Teamwire client application, i.e. a Teamwire user using multiple clients results in multiple connectors being used simultaneously.
Connectors are created automatically by the Teamwire backend through either - registration of a new installation of a mobile or desktop client, or - logging on to an existing Teamwire user account with a login password.
In the latter case it is possible that a user performs a logout, in this
case the connector will be deleted. In the former case the connector
will stay existant as long as it is being used at least once within
the organisation’s connector_retention_period.
Manage Teamwire connectors
Modify an existing connector
PUT /v<api_version>/admin/connectors/<connector_id>/
This endpoint can be used to exercise administrative control over individual connectors and thereby end devices. Currently the only modification possible is to change the connector’s state:
Enabledmeans the connector can be used to communicate with the client API.Disabledmeans applications accessing the client API will receive an error message until the connector is reenabled again, thereby effectively locking the user out on this device/installation.Wipeis used to instruct Teamwire clients that not only access is blocked but all personal data present on the local device/installation should be wiped.
Note that there are two other states, Pending (a client has
registered but not confirmed his email address yet) and Wiped
(the client has wiped all locally present personal data, the
connector can now be deleted.), however these can not be set
through the Enterprise API.
Access restrictions
- Admins and Superadmins must have the allow_modify_users permission.
- Admins can modify connectors of users in their own organisation only.
- Superadmins can modify connectors of users 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. |
| connector_id | String | No | All admins | The ID of the connector to be updated. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
connector_state |
String | No | All admins | The new state for the connector: one of Enabled, Disabled or Wipe. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the connector has been updated. |
| 400 (Bad request) | The request failed because an invalid connector state was specified. |
| 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 either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and a connector was specified that does not belong to the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified connector could not be found. |
| 409 (Conflict) | The request failed because either a.) the connector is in state Enabled or Wipe or b.) the organisation the connector belongs to has been disabled. |
Delete an existing connector
DELETE /v<api_version>/admin/connectors/<connector_id>/
Deleting a connector means that the Teamwire client application using this connector will lose all access to the client API and will require the user to reregister respectively log in again.
Only connectors in the states Pending (registration has begun
but is not finished yet, e.g. because the user didn’t confirm his
email address yet), Disabled (the connector
has been disabled before) and
Wiped (the mobile/desktop client application has confirmed that
it has wiped all personal data from the device) can be deleted.
A connector in the state Enabled must be set to Disabled
in order to be deletable. For a connector in state Wipe the
wiping process must have completed first.
Access restrictions
- Admins and Superadmins must have the allow_modify_users permission.
- Admins can delete connectors of users in their own organisation only.
- Superadmins can delete connectors of users 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. |
| connector_id | Number | No | All admins | The ID of the connector 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 connector 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 either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and a connector was specified that does not belong to the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified connector could not be found. |
| 409 (Conflict) | The request failed because either a.) the connector is in state Enabled or Wipe or b.) the organisation the connector belongs to has been disabled. |