Skip to main content

Managing Users

tech writers
  • Updated

Cyara provides APIs for managing users. The examples describe how to automate certain user administration tasks such as creating new users, attach or detach users from accounts, viewing list of users attached to an account, delete users, and view the list of available user roles.

The examples in this article use Python because of its easy to read syntax and popularity. You may use any programming language of your choice to write the code.

The Cyara US portal https://cyaraportal.us/cyarawebapi is used as the base URL in the examples. If you are using one of the other Portals that Cyara provides, you must change the URL to reflect the Portal you are utilizing.

Prerequisites

  • You must have user administrative privileges to use the APIs described in this article.
  • All requests to the API must include an authentication token in the request header. For information about getting your API key, see Authentication.
  • Cyara entity IDs such as userID and AccountID. For information about getting the IDs, see Cyara Entity IDs and GUIDs
  • A working Python environment on your computer.

Retrieving User Details

This end point fetches the profile information of users by their userID, which is a unique identifier for each user. 

API endpoint: /v3.0/users/{userId}

Request method: GET

The following example fetches the details of a user with userID d81e97d1-547c-42f6-a29c-63a4d23393e2 with Content-Type set to application/json.

import requests

url = "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [enter your key here]"
r=requests.get(url, headers=header)
print(r.content)
print(r.status_code)

 

Response

A successful API call returns a status of 200 and the profile information of the user. Following is the sample response body:

{
  "userId": "d81e97d1-547c-42f6-a29c-63a4d23393e2",
  "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2",
  "locked": false,
  "lockoutEnabled": true,
  "lockoutEndDate": null,
  "dateCreated": "2022-01-14T02:07:38.7497706Z",
  "lastLoginDate": null,
  "defaultAccount": 1,
  "username": "test.demo",
  "firstname": "Test",
  "lastname": "Demo",
  "telephone": "21159666699",
  "mobile": "1546547756431",
  "email": "testdemo@cyara.com",
  "active": true,
  "platformNotifications": true,
  "fullScreen": true,
  "roles": [
    "QAAnalyst"
  ],
  "loginProviders": [
    "Identity"
  ]
}

Retrieving List of Users

This end point fetches a paginated list of all users in the Platform. sortfield parameter can be specified to sort the results and sortasc can be set to true or false to sort the results by ascending order. By default, the response is sorted in ascending order of the username.

API endpoint: /v3.0/users

Request method: GET

import requests

url = "https://www.cyaraportal.us/cyarawebapi/v3.0/users"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [enter your key here]"
r=requests.get(url, headers=header)
print(r.content)
print(r.status_code)

Response

A successful API call returns a status of 200 and a paginated list of users along with their profile information. Following is the sample response body formatted in JSON and the search results are sorted in ascending order of the user's last name:

{
  "firstPage": "https://www.cyaraportal.us/cyarawebapi/v3.0/users?sortfield=lastname&sortasc=true&pageno=1",
  "lastPage":  "https://www.cyaraportal.us/cyarawebapi/v3.0/users?sortfield=lastname&sortasc=true&pageno=1",
  "nextPage": null,
  "previousPage": null,
  "results": [
    {
      "userId": "0b53c6e8-505a-4e5c-8a7a-2c942ee32353",
      "active": true,
      "username": "demouser",
      "firstname": "Cyara",
      "lastname": "Demo",
      "email": "cyarademo@cyara.com",
      "telephone": "982373434",
      "mobile": null,
      "roles": [
        "UserAdmin"
      ],
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/0b53c6e8-505a-4e5c-8a7a-2c942ee32353"
    },
    {
      "userId": "d81e97d1-547c-42f6-a29c-63a4d23393e2",
      "active": true,
      "username": "test.demo",
      "firstname": "Test",
      "lastname": "Demo",
      "email": "testdemo@cyara.com",
      "telephone": "21159666699",
      "mobile": "1546547756431",
      "roles": [
        "QAAnalyst"
      ],
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2"
    },
    {
      "userId": "91101b12-7149-4e9f-88b8-a6e0ba40e6c2",
      "active": true,
      "username": "UserDemo",
      "firstname": "Cyara",
      "lastname": "Demo",
      "email": "cyarademo@cyara.com",
      "telephone": "982373434",
      "mobile": null,
      "roles": [
        "UserAdmin"
      ],
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/91101b12-7149-4e9f-88b8-a6e0ba40e6c2"
    },
    {
      "userId": "0142a112-e8c0-4e92-afb8-636e0ba90880",
      "active": true,
      "username": "admin",
      "firstname": "First",
      "lastname": "Last",
      "email": "support@cyara.com",
      "telephone": "99999999",
      "mobile": null,
      "roles": [
        "Billing",
        "PlatformUserAdmin",
        "Admin",
        "DashboardAdmin",
        "ExecutiveDashboard",
        "CCMReporting",
        "Marketing",
        "PlatformUser",
        "UserAdmin",
        "CCMAdmin",
        "Reporting",
        "PlatformAdmin"
      ],
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/0142a112-e8c0-4e92-afb8-636e0ba90880"
    },
    {
      "userId": "0690148e-8f2f-473c-b130-635d4fcaa08c",
      "active": true,
      "username": "test.user",
      "firstname": "Test",
      "lastname": "User",
      "email": "testuser@email.com",
      "telephone": "0983699002",
      "mobile": "33248098089",
      "roles": [
        "BusinessAnalyst",
        "QAEngineer"
      ],
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/0690148e-8f2f-473c-b130-635d4fcaa08c"
    }
  ],
  "totalResults": 5,
  "returnedResults": 5
}

Retrieving List of User Roles

This end point fetches all the user roles that are available in the Platform. Sort parameter and sort order can also be specified. By default, the response is sorted in ascending order of the name.

For more information on the differences between available Cyara User Roles, read the User Roles Summary Article here. 

API endpoint: /v3.0/roles

Request method: GET

The following example fetches the list of user roles.

import requests
url = "https://www.cyaraportal.us/cyarawebapi/v3.0/roles"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [Enter your key here]"
r=requests.get(url, headers=header)
print(r.content)
print(r.status_code)

 

Response

A successful API call returns a status of 200 and a paginated list of roles available in the Platform. Following is the sample response body formatted in JSON:

{
  "firstPage": "https://www.cyaraportal.us/cyarawebapi/v3.0/roles?sortasc=true&pageno=1",
  "lastPage": "https://www.cyaraportal.us/cyarawebapi/v3.0/roles?sortasc=true&pageno=1",
  "nextPage": null,
  "previousPage": null,
  "results": [
    "Administration",
    "Billing",
    "BusinessAnalyst",
    "BusinessExecutive",
    "VirtualAgentAdministration",
    "VirtualAgentReporting",
    "ExecutiveDashboardAdmin",
    "DevelopmentEngineer",
    "DevelopmentLead",
    "ExecutiveDashboard",
    "Marketing",
    "OperationsEngineer",
    "OperationsLead",
    "PlatformAdministrator",
    "PlatformUser",
    "PlatformUserAdministrator",
    "QAAnalyst",
    "QAEngineer",
    "QALead",
    "Reporting",
    "UserAdmin"
  ],
  "totalResults": 21,
  "returnedResults": 21
}

 

Retrieving List of Accounts for the User

This end point fetches all the accounts that the specified user is attached.

API endpoint: /v3.0/users/{userId}/accounts

Request method: GET

import requests
url = "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2/accounts"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [Enter your key here]"
r=requests.get(url, headers=header)
print(r.content)
print(r.status_code)
 

Response

A successful API call returns a status of 200 and a paginated list of accounts that the specified user is attached to. Following is the sample response body formatted in JSON:

{
  "firstPage": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2/accounts?pageno=1",
  "lastPage": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2/accounts?pageno=1",
  "nextPage": null,
  "previousPage": null,
  "results": [
    {
      "accountId": 1,
      "name": "Test",
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/accounts/1"
    },
    {
      "accountId": 2,
      "name": "demoadmin",
      "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/accounts/2"
    }
  ],
  "totalResults": 2,
  "returnedResults": 2
}

Creating New User

This end point creates a new user with the specified parameters. 

API endpoint: /v3.0/users/{userId}/accounts

Request method: POST

Request payload: username, firstname, lastname, email, telephone, mobile, roles, active, defaultAccount, loginProviders, password

import requests
url = "https://www.cyaraportal.us/cyarawebapi/v3.0/users"
userdetails = {'username':'test.demo', 'firstname':'Test', 'lastname':'Demo', 'email':'testdemo@cyara.com', 'active':'true', 'defaultAccount':'1', 'roles':'QAAnalyst', 'loginProviders':'Identity', 'telephone':'21159666699', 'mobile':'1546547756431'}
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
#header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [Enter your key here]"
r=requests.post(url, headers=header, data = userdetails)
print(r.content)
print(r.status_code)
 

Response

A successful API call returns a status of 200 and the details of the new user along with the userID. Following is the sample response body formatted in JSON:

{
  "userId": "d81e97d1-547c-42f6-a29c-63a4d23393e2",
  "url": "https://www.cyaraportal.us/cyarawebapi/v3.0/users/b7682560-f65a-4dc7-af07-bc9304a61be8",
  "locked": false,
  "lockoutEnabled": true,
  "lockoutEndDate": null,
  "dateCreated": "2022-01-20T00:04:26.7031268Z",
  "lastLoginDate": null,
  "defaultAccount": 1,
  "username": "test.demo",
  "firstname": "Test",
  "lastname": "Demo",
  "telephone": "21159666699",
  "mobile": "1546547756431",
  "email": "testdemo@cyara.com",
  "active": true,
  "platformNotifications": true,
  "fullScreen": true,
  "roles": [
    "QAAnalyst"
  ],
  "loginProviders": [
    "Identity"
  ]
}

Creating Users in Bulk

You can create users in bulk by importing user details in a CSV file.

API endpoint: /v3.0/users

Request method: POST

Request payload: username, firstname, lastname, email, telephone, mobile, roles, active, defaultAccount, loginProviders, password

import requests
import csv
import os
import json

url = "https://cyaraportal_hostname/cyarawebapi/v3.0/users" 
account_id = 'insert_your_accountID'
userdetails = {'username':'test.demo', 'firstname':'Test', 'lastname':'Demo', 'email':'testdemo@cyara.com', 'active':'true', 'defaultAccount':'1', 'roles':'QAAnalyst', 'loginProviders':'Identity', 'telephone':'21159666699', 'mobile':'1546547756431'}
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Authorization"] = "ApiKey [insert your API Key]"
csv_file = "d:\\Cyara\\cyara_users.csv"
## let's create functions first
# function to create an individual user
def create_user(url,header,userdetails):
    r=requests.post(url, headers=header, data = userdetails)
    #print(r.content)
    print(r.status_code)
    return r.content,r.status_code
# function to read the csv file and create user one after another
def create_users(csv_file):
    firstrow = ['Account','Username','Surname','FirstName','Telephone','Mobile','Email','Roles','Active']
    with open(csv_file, mode='r', encoding='utf-8') as f:
        csv_reader = csv.DictReader(f)
        for row in csv_reader:
            roles = row['Roles'].split(',')
            print (roles)
            userdetails={'username':row['Email'],'firstname':row['FirstName'],'lastname':row['Surname'],'email':row['Email'],'active':row['Active'],'defaultAccount':account_id,'roles':roles ,'loginProviders':'Saml','telephone':'123','mobile':'123'}
            print (userdetails)
            create_user(url,header,userdetails)
            #os.system("pause")
### Let's start processing now ###
create_users(csv_file)
# The End

Response

A successful API call returns a status of 200 and the details of all the new users along with their userID.

Attaching User to Account

There are two end points that can attach a user to a specified account. 
 

API endpoint: /v3.0/users/{userId}/accounts/{accountID}

                        /v3.0/accounts/{accountID/users/{userId}

Request method: PUT

import requests
url = "https://www.cyaraportal.us/cyarawebapi/v3.0/accounts/2/users/d81e97d1-547c-42f6-a29c-63a4d23393e2"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [Enter your key here]"
r=requests.put(url, headers=header)
print(r.content)
print(r.status_code)

 

Response

A successful API call returns a status of 200.

 

Attaching Users to an Account in Bulk

You can attach multiple Users to an Account in bulk using a CSV file.
 

API endpoint: /v3.0/accounts/{accountID/users/{userId}

import requests
import csv
import os
import json

url = "https://cyara_url/cyarawebapi/v3.0/users" 
account_id = 'account_id'
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
#header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey api key"
csv_file = "d:\\Cyara\\cyara_users.csv"

def get_users(account_id):
    a = requests.get('https://cyaraportal.us/cyarawebapi/v3.0/accounts/'+account_id+'/users?pageSize=1000', headers=header).text
    allusers = json.loads(a)
    users = allusers['results']
    return (users)

def attach_user(user,csv_file):
    with open(csv_file, mode='r', encoding='utf-8') as f:
        csv_reader = csv.DictReader(f)
        for row in csv_reader:
            if row['Email'] == user['username']:
                print ('Attaching username: '+user['username']+' to its account: '+row['Account'])
                at_url = 'https://cyaraportal.us/cyarawebapi/v3.0/accounts/'+row['Account']+'/users/'+user['userId']
                result = requests.put(at_url,headers=header)
                print ('response code: '+str(result.status_code))
#### Now let's go through the list one more time and attach users to their accounts. ####
#### It can be done in one iteration, but for simplicity let's do it sequentually.   ####
(users)=get_users(account_id=)
for user in users:
    print ('username: '+str(user['username']))
    attach_user(user,csv_file)

Response

A successful API call returns a status of 200.

Detaching User From Account

There are two end points that can detach a user from a specified account. 

API endpoint: /v3.0/users/{userId}/accounts/{accountID}

                        /v3.0/accounts/{accountID/users/{userId}

Request method: DELETE

import requests
url = "https://www.cyaraportal.us/cyarawebapi/v3.0/accounts/2/users/d81e97d1-547c-42f6-a29c-63a4d23393e2"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [Enter your key here]"
r=requests.delete(url, headers=header)
print(r.content)
print(r.status_code)

 

Response

A successful API call returns a status of 200.

 

Deleting User

This end point deletes the specified user from the Platform.

API endpoint: /v3.0/users/{userId}

Request method: DELETE

import requests
url = "https://www.cyaraportal.us/cyarawebapi/v3.0/users/d81e97d1-547c-42f6-a29c-63a4d23393e2"
header = requests.structures.CaseInsensitiveDict()
header["accept"] = "application/json"
header["Content-Type"] = "multipart/form-data"
header["Authorization"] = "ApiKey [Enter your key here]"
r=requests.delete(url, headers=header)
print(r.content)
print(r.status_code)

 

Response

A successful API call returns a status of 200.

 

 

Related articles

Comments

0 comments

Please sign in to leave a comment.