organization_user_management_api.md

Quick start

---

This API allows organization owners to add users to, delete users from or modify users in their organization.

The endpoint is <org>.cartodb.com/u/<org_owner>/api/v1/organization/<org>/users.

Create a user

The parameters sent (via POST; * means they're compulsory) are:

• username (*) - username for the new user
• email (*) - email for the new user
• password (*) - password for the new user
• api_key (*) - the organization's owner Api key (can also be specified as a URL param).
• soft_geocoding_limit - if set to true, the user will be allowed to exceed the geocoding limit imposed. If not specified, it's set to false by default.
• quota_in_bytes - amount of quota from the organization assigned to the new user. If not specified, the default quota for new users specified for the organization is used.

Example:

curl -H 'Content-Type: application/json' sample-org.cartodb.com/u/org-owner/api/v1/organization/sample-org/users -X POST --data '{"user":"org-sub", "email":"org-sub@sample-org.com", "password":"secret!", "api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f"}'

If the request is succesful, a representation of the new user (with code 200) is returned like:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "org-user",
  "email":"org-user@org.com",
  "avatar_url":"//example.com/avatars/avatar_stars_blue.png",
  "base_url":"http://dev-org.cartodb.com/u/org-user",
  "quota_in_bytes":104857600,
  "db_size_in_bytes":0,
  "table_count":0,
  "public_visualization_count":0,
  "all_visualization_count":0
}

Update a user

The user to be updated should be specified via their username like: <org>.cartodb.com/u/<org_owner>/api/v1/organization/<org>/users/<org_user>

The parameters sent (via PUT; * means they're compulsory) are:

• email - new email for the user
• password - new password for the user
• api_key (*) - the organization's owner Api key (can also be speficied as a URL param).
• soft_geocoding_limit - if set to true, the user will be allowed to exceed the geocoding limit imposed by a small amount.
• quota_in_bytes - amount of quota from the organization to be assigned to the user.

Example:

curl -H 'Content-Type: application/json' sample-org.cartodb.com/u/org-owner/api/v1/organization/sample-org/users/org-sub -X PUT --data '{"email":"org-sub-2@sample-org.com", "password":"new_secret!", "api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f"}'

If the request is succesful, a representation of the new user (with code 200) is returned like:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "org-user",
  "email":"org-user@org.com",
  "avatar_url":"//example.com/avatars/avatar_stars_blue.png",
  "base_url":"http://dev-org.cartodb.com/u/org-user",
  "quota_in_bytes":104857600,
  "db_size_in_bytes":0,
  "table_count":0,
  "public_visualization_count":0,
  "all_visualization_count":0
}

Show a user's information

The user to be shown should be specified via their username like: <org>.cartodb.com/u/<org_owner>/api/v1/organization/<org>/users/<org_user>

The parameters sent (via GET; * means they're compulsory) are:

• api_key (*) - the organization's owner Api key.

Example:

curl -H 'Content-Type: application/json' sample-org.cartodb.com/u/org-owner/api/v1/organization/sample-org/users/org-sub?api_key=1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f -X GET

If the request is succesful, a representation of the new user (with code 200) is returned like:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "org-user",
  "email":"org-user@org.com",
  "avatar_url":"//example.com/avatars/avatar_stars_blue.png",
  "base_url":"http://dev-org.cartodb.com/u/org-user",
  "quota_in_bytes":104857600,
  "db_size_in_bytes":0,
  "table_count":0,
  "public_visualization_count":0,
  "all_visualization_count":0
}

Delete a user

The user to be deleted should be specified via their username like: <org>.cartodb.com/u/<org_owner>/api/v1/organization/<org>/users/<org_user>

The parameters sent (via DELETE; * means they're compulsory) are:

• api_key (*) - the organization's owner Api key (can also be speficied as a URL param).

Example:

curl -H 'Content-Type: application/json' sample-org.cartodb.com/u/org-owner/api/v1/organization/sample-org/users/org-sub -X DELETE --data '{"api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f"}'

If the request is succesful, a string saying "User deleted" (with code 200) is returned.