Managing Users via the Compose API

The Compose API offers many ways to manage the Users on your account. The main endpoints that allow user management on the account-level are:

/2016-07/user
/2016-07/accounts/:id/users/
/2016-07/accounts/:id/users/:user_id

A full API reference can be found in the API Documentation.

Current User

You can find the user associated with the API token in use by sending a GET request to the /2016-07/user endpoint.

export API_TOKEN=your_api_token
curl -X GET -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" "https://api.compose.io/2016-07/user"`

The response will give you the id and name of the user assigned this API token.

List Users

List all users on an account by sending a GET request to /2016-07/accounts/:id/users/ with the account id.

export API_TOKEN=your_api_token
export ACCOUNT_ID=your_account_id
curl -X GET -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" "https://api.compose.io/2016-07/accounts/${ACCOUNT_ID}/users"

The endpoint will return an embedded object containing all users by name and id.

Add User

To add a user to your account, send a POST request to the /2016-07/accounts/:id/users/ endpoint.
The body parameter requires that you specify a new user's name and email address, there is also an optional "phone" field.

export API_TOKEN=your_api_token
export ACCOUNT_ID=your_account_id
curl -X POST "https://api.compose.io/2016-07/accounts/${ACCOUNT_ID}/users" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d ' {
  "name": "Lawrence Waterhouse",
  "email": "[email protected]",
  "phone": 613-555-0101"
}'

Once created, the endpoint returns the new user id and name. This will also create a new account for the user and send them an email at the email address you provided, so they can continue to set up and log into Compose.

Delete User

To delete a user from your account, send a DELETE request to /2016-07/accounts/:id/users/ with the id of the user that you want to remove.

export API_TOKEN=your_api_token
export USER_ID=user_id_to_remove
curl -X DELETE 'https://api.compose.io/2016-07/accounts/${ACCOUNT_ID}/users/${USER_ID}'  \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json"

The response will contain the user's name and id; neither of which will be associated with your account.

User Roles

Currently, there is no way to manage user roles on an account level via the Compose API. To manage the roles assigned to your teams, please use the Users section of your Account in the Compose application. For more information please see the Compose Access Controls page.

Still Need Help?

If this article didn't solve things, summon a human and get some help!