Hey! This content applies only to previous CARTO products

Please check if it's relevant to your use case. On October 2021 we released a new version of our platform.
You can learn more and read the latest documentation at docs.carto.com

Questions / Your Account & Plan / Enterprise

Enterprise User Management API

Authenticated organization administrators and owners can use the Enterprise User Management API to manage users programmatically.

The Enterprise User Management API enables organization “owners” programmatically add, delete, show, or update users from their account. (“Admins” can add users). By making a simple request with parameters to the API, administrators can easily manage large amounts of users without having to use the Account options. For example, suppose your organization has a large CSV or JSON file containing various employee information (such as username, email, passwords, and so on). Instead of manually adding details of each employee with the CARTO Enterprise account options, the organization owner can use this API to program a script to request this information directly from this CSV or JSON file.

Tip: See this Use Case example for how to program a script to import users into a CARTO organization from a CSV or JSON file.

Currently, you can add, delete, show, or update organization users with the Enterprise User Management API.

Create Users with the Enterprise API

To create new users, make a POST request with the following parameters. The web service endpoint URL for running scripts with the POST command is:

<org>.carto.com/u/<org_owner>/api/v2/organization/<org>/users

Arguments

Name	Description	Required
username	the username of the new organization user.	Required
viewer	each user can be assigned write and read access (Builder) or read-only access (Viewer) to shared datasets and maps.	Optional Tip: If not specified, the new user will automatically have Builder (write and read access), `viewer: false`. To assign read-only access to a new user, apply `viewer: true`.
org_admin	assign admin access to a Builder user by applying `org_admin: true`.	Optional If not specified, the default is ‘false’ (no admin privileges).
email	email of the new organization user. Only the organization owner can see this parameter.	Required
password	password of the new organization user.	Required Note: If the organization owner enabled the Auth settings Strong Passwords through the dashboard, then all organization users created through the API are required to create strong passwords for login.
api_key	the organization owner API Key. Tip: The organization owner can copy their API Key from their Account settings.	Required
soft_geocoding_limit	determines the geocoding limit imposed for the organization user. If not specified, this is set to `false` by default and enables the user to exceed the geocoding limit. You can only use this option if you have it enabled. Contact support for more information.	Optional
quota_in_bytes	assigns the data usage quota to the organization user. If not specified, the default quota specified by the organization is applied.	Optional

Returns

A success message representing the newly created user(s) (code 200).

Example

The following example request and return describes how to add new organization users with the Enterprise API.

Request

curl -H 'Content-Type: application/json' https://sample-org.carto.com/u/org-owner/api/v2/organization/sample-org/users -X POST --data '{"username":"org-user", "viewer":true, "org_admin":false, "email":"org-user@sample-org.com", "password":"secret!", "api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f"}'

Returns

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

Update Users with the Enterprise API

To update existing organization users, make a PUT request with the following parameters. The web service endpoint URL for running scripts with the PUT command is:

<org>.carto.com/u/<org_owner>/api/v2/organization/<org>/users/org-user

Note: Only Enterprise owners have access to run the update command.

Arguments

Name	Description	Required
email	new email for the modified user.	Optional
password	new password for the modified organization user.	Optional
api_key	the organization owner API Key. Tip: The organization owner can copy their API Key from their Account settings.	Required
soft_geocoding_limit	determines the geocoding limit imposed for the organization user. If not specified, this is set to `false` by default and enables the user to exceed the geocoding limit.	Optional
quota_in_bytes	assigns the data usage quota to the organization user. If not specified, the default quota specified by the organization is applied.	Optional
viewer	Updates the access role of an existing user. To assign write-access, apply `viewer: false`. To assign read-only access, apply `viewer: true`. Tip: If not specified, the user access role remains the same and is not updated.	Optional
org_admin	assign admin access to a Builder user by applying `org_admin: true`.	Optional If not specified, the default is ‘false’ (no admin privileges).

Returns

A success message representing the modified user(s) (code 200).

Example

The following example request and return describes how to modify existing organization users with the Enterprise API.

Request

curl -H 'Content-Type: application/json' sample-org.carto.com/u/org-owner/api/v2/organization/sample-org/users/org-user -X PUT --data '{"email":"org-user-2@sample-org.com", "password":"new_secret!", "api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f","viewer":true, "org_admin":false,}'

Returns

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "org-user",
  "email":”org-user-2@sample-org.com”,
  "avatar_url":"//example.com/avatars/avatar_stars_blue.png",
  "base_url":"http://sample-org.carto.com/u/org-user",
  "quota_in_bytes":104857600,
  "db_size_in_bytes":0,
  "table_count":0,
  "public_visualization_count":0,
  "all_visualization_count":0
  "viewer":true
  "org_admin":false
}

Show Users with the Enterprise API

To display and show an organization user with the Enterprise API, make a GET request with the following parameters. The web service endpoint URL for running scripts with the GET command is:

<org>.carto.com/u/<org_owner>/api/v2/organization/<org>/users/org-user

Note: Only Enterprise owners have access to run the show command.

Arguments

Name	Description	Required
api_key	the organization owner API Key. Tip: The organization owner can copy their API Key from their Account settings.	Required

Returns

A success message representing the displayed user(s) (code 200).

Example

The following example request and return describes how to show existing organization users with the Enterprise API.

Request

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

Returns

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

Delete Users with the Enterprise API

To delete existing organization users, make a DELETE request with the following parameters. The web service endpoint URL for running scripts with the DELETE command is:

<org>.carto.com/u/<org_owner>/api/v2/organization/<org>/users/org-user

Arguments

Name	Description	Required
api_key	the organization owner API Key. Tip: The organization owner can copy their API Key from their Account settings.	Required

Returns

A success message confirming the organization user(s) (code 200) has been deleted.

Example

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

Configure multi-factor authentication with the Enterprise API

To configure multi-factor authentication for an existing organization user, make a POST request to this service endpoint URL:

<org>.carto.com/u/<org_owner>/api/v2/organization/<org>/users/org-user/mfa/<type>

Arguments

Name	Description	Required
type	The multi-factor authentication type to enable. The only supported type is `totp`	Required
api_key	the organization owner API Key. Tip: The organization owner can copy their API Key from their Account settings.	Required

Returns

A success message confirming the multi-factor authentication has been configured (code 201).

Example

curl -H 'Content-Type: application/json' sample-org.carto.com/u/org-owner/api/v2/organization/sample-org/users/org-user/mfa/totp -X POST --data '{"api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f"}'

Disable multi-factor authentication with the Enterprise API

To disable multi-factor authentication for an existing organization user, make a DELETE request to this service endpoint URL:

<org>.carto.com/u/<org_owner>/api/v2/organization/<org>/users/org-user/mfa/<type>

Arguments

Name	Description	Required
type	The multi-factor authentication type to enable. The only supported type is `totp`	Required
api_key	the organization owner API Key. Tip: The organization owner can copy their API Key from their Account settings.	Required

Returns

A success message confirming the multi-factor authentication has been disabled (code 204).

Example

curl -H 'Content-Type: application/json' sample-org.carto.com/u/org-owner/api/v2/organization/sample-org/users/org-user/mfa/totp -X DELETE --data '{"api_key":"1a9eda3a51e43f8aa52e1fbcb949aaddee3b1d9f"}'

Use Case: Importing Users into a CARTO Organization from a CSV or JSON file

This is an example of how a program can use the Enterprise Users Management API to create, update, or delete users from a CSV or a JSON file.

We use two python files: secrets.py containing the owners credentials (name, API Key and org name) and manage_users.py with the code to be run.

# manage_users.py
# encoding: utf-8

# Usage:
#     manage_users.py <action> <filename>
#
# Supported actions:
#     create
#     update
#     delete
#
# Supported file extensions
#     .csv
#     .json

import csv, json, sys

from httplib2 import Http
from urllib import urlencode

try:
  from secrets import *
except Exception, e:
  print('You need a secrets.py file')

supported_actions = {
                      'update': 'PUT',
                      'create': 'POST',
                      'delete': 'DELETE'
                    }

supported_extensions = ['.csv', '.json']

def main():
  parse_arguments()

  users = load_users_from_file(filename)

  base_url = 'https://' + org_name + '.carto.com/u/' + owner_username + '/api/v2/organization/' + org_name + '/users/'

  for user in users:
    params = user.copy() # copy user attributes into params

    params['api_key'] = api_key # add api key to params

    url = base_url if action == 'create' else base_url + params['username']

    response, content = Http().request(url, method, urlencode(params))

    handle_response(response, content, user)


def load_users_from_file(filename):
  if filename.endswith('.json'):
    with open(filename) as users_file:
      return json.load(users_file)['users']
  elif filename.endswith('.csv'):
    with open(filename) as users_file:
      return list(csv.DictReader(users_file))
  else:
    print('File format not supported')
    print_usage()


def handle_response(response, content, user):
  code = response['status']

  if code == '200':
    print('%s user %s successful' % (action, user['username']))
  elif code == '410':
    print('Some params were wrong for %s:' % user['username'])
  elif code == '401':
    print('Auhtentication error.')
  else:
    print('Unknown error.')

  print(content)


def parse_arguments():
  global program_name, action, filename, method

  try:
    program_name = sys.argv[0]
    action = sys.argv[1]
    filename = sys.argv[2]

    method = supported_actions[action]
  except Exception, e:
    print_usage()
    sys.exit(-1)


def print_usage():
  print("Usage:")
  print("\t%s <action> <filename>" % program_name)
  print
  print("Supported actions:")
  for action in supported_actions.keys():
    print("\t%s" % action)
  print
  print("Supported file extensions")
  for action in supported_extensions:
    print("\t%s" % action)
  print


if __name__ == '__main__':
  main()

# secrets.py

api_key = '875e43adaa8fdd7ffec88aa5d38cf230403f656f'
org_name = 'niceorg'
owner_username = 'owner'

Additionally, include a CSV file with the users’ information:

# users.csv

username,email,password,quota_in_bytes,soft_geocoding_limit
bob,bob@niceorg.com,bobsecret!,,
alice,alice@niceorg.com,alicesecret!,,true
alex,alex@niceorg.com,alexsecret!,300000000,true
sandy,sandy@niceorg.com,sandysecret!,100000000,

Alternatively, you can use a JSON file containing the users’ information:

# users.json

{
  "users" : [
    {
      "username": "bob",
      "email": "bob@niceorg.org",
      "password": "bobsecret!"
      "viewer":false
    },
    {
      "username": "alice",
      "email": "alice@niceorg.org",
      "password": "alicesecret!",
      "soft_geocoding_limit": true
      "viewer":true
      "org_admin":false
    },
    {
      "username": "alex",
      "email": "alex@niceorg.org",
      "password": "alexsecret!",
      "quota_in_bytes": 300000000,
      "soft_geocoding_limit": true
      "viewer":true
      "org_admin":false
    },
    {
      "username": "sandy",
      "email": "sandy@niceorg.org",
      "password": "sandysecret!",
      "quota_in_bytes": 100000000
      "viewer":false
      "org_admin":false
    }
  ]
}

Here are some examples of program scripts:

$ python manage_users.py create users.csv # creates users from users.csv
$ python manage_users.py delete users.json # deletes users in users.json
$ python manage_users.py update users.csv # updates users info for users.csv