Your search returned no results

Try another search term or view Stack Exchange, where we have active conversations with Developers about GIS.

    http://gis.stackexchange.com/
    Support channel in Stack Exchange

    Thousands of developers around the world have helped make CartoDB a success, and we have active conversations with them about GIS in Stack Exchange.

    Go to Stack Exchange

    Enterprise User Management API

    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://dev-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://dev-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://dev-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"}'

    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