This content applies to a previous version of CARTO

In October 2021 we released a new version of our platform. You can find the latest documentation at docs.carto.com

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 to 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 the 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
org_admin	Assign admin access to a Builder user by applying `org_admin: true`.	Optional
email	Email of the new organization user. Only the organization owner can see this parameter.	Required
password	Password of the new organization user.	Required
api_key	The organization owner API Key.	Required
soft_geocoding_limit	Determines the geocoding limit imposed for the organization user.	Optional
quota_in_bytes	Assigns the data usage quota to the organization user.	Optional

Returns

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

Example

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.	Required
soft_geocoding_limit	Determines the geocoding limit imposed for the organization user.	Optional
quota_in_bytes	Assigns the data usage quota to the organization user.	Optional
viewer	Updates the access role of an existing user.	Optional
org_admin	Assign admin access to a Builder user by applying `org_admin: true`.	Optional

Returns

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

Example

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.	Required

Returns

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

Example

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.	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.	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.	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:

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" : [
    {
      "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

Spatial Analysis in 2025: Key Trends Report

| Download Now

Enterprise User Management API

Create Users with the Enterprise API

Arguments

Returns

Example

Request

Returns

Update Users with the Enterprise API

Arguments

Returns

Example

Request

Returns

Show Users with the Enterprise API

Arguments

Returns

Example

Request

Returns

Delete Users with the Enterprise API

Arguments

Returns

Example

Configure multi-factor authentication with the Enterprise API

Arguments

Returns

Example

Disable multi-factor authentication with the Enterprise API

Arguments

Returns

Example

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