New Xton Documentation Center
Xton help has moved. Please visit the current version of this page for the most recent updates. Our new documentation center can be found at help.xtontech.com.
Getting Started Guide using REST APIs in Shell with Xton Access Manager.
This page outlines several specific scenarios in which REST APIs in XTAM can be called using Shell scripts. Please note that security is strictly enforced, so ensure the account executing the scripts has the appropriate permissions to access the objects in XTAM.
To view XTAM’s full, interactive REST API utilizing the OpenAPI format, navigate to Adminstration > Settings > Application Nodes > API Documentation.
Looking for REST API examples using other scripts? Click PowerShell examples, Shell examples, VBScript examples or Python examples for additional information.
The following scripts are provided as an example of what is possible, however they can and should be customized to meet your requirements including outside script integration, formatting and proper error handling.
Please note that our examples include use of curl for execution and jq for JSON parsing. Ensure these packages are deployed prior to executing the scripts or customize them to fit your needs.
- Create a Record
- Create a Folder
- Retrieve Root Folder
- List Folder Content
- Retrieve a Record
- Retrieve a Record with Password (Unlock)
- Retrieve a Record Field (Unlock)
- Update a Record
- Download a File
- Share a Record or Folder
- Delete a Record
- Search for Objects (Record or Folder)
- List Record Types
- Database Export (Decrypted)
- Database Export (Encrypted)
- Database Import
Create a Record
Provides the ability to create a new record with the defined parameters.
folderId="183320" # ID of Parent Folder typeId="1724" # ID of Record Type recordName="Record Name" # Record Name (required) recordDescription="Record Description" # Record Description (optional) rhost="host.company.com" # Host URL rport="22" # Host Port ruser="user" # Host User rpassword="myPassw0rd" # Host Password rparameters={\"Host\":\"$rhost\",\"Port\":\"$rport\",\"User\":\"$ruser\",\"Password\":\"$rpassword\"} curl -s $auth -H "Accept: application/json" -H "Content-Type:application/x-www-form-urlencoded" -H "X-XSRF-TOKEN: $apitoken" -X POST \ --data "name=$recordName&description=$recordDescription" --data-urlencode "custom=$rparameters" \ $url/rest/record/new/$folderId/$typeId echo Done
Create a Folder
Provides the ability to create a new folder with the defined parameters.
folderId="183320" # ID of Parent Folder folderName="Folder Name" # Folder Name (required) folderDescription="Folder Description" # Folder Description (optional) curl -s $auth -H "Accept: application/json" -H "Content-Type:application/json" -H "X-XSRF-TOKEN: $apitoken" -X POST \ --data "{\"name\":\"$folderName\",\"description\":\"$folderDescription\"}" $url/rest/folder/create/$folderId echo Done
Retrieve Root Folder
Provides the ability to retrieve the Root Folder (All Records) and its parameters including ID.
rootFolder=$(curl -s $auth $url/rest/folder/root) rootFolderId=$(echo $rootFolder | jq -r '.id') #echo $rootFolder # Retrieve all Root Folder parameters echo id:$rootFolderId # Retrieve Root Folder ID echo Done
List Folder Content
Provides the ability to list all content of the specified folder.
folderId="183320" # Folder ID allContent=$(curl -s $auth $url/rest/folder/list/$folderId) allNamesOnly=$(echo $allContent | jq '.[] | .name, .id') #echo $allContent # Get all Content parameters echo $allNamesOnly # Get all Content "Names" and ID only echo Done
Retrieve a Record
Provides the ability to retrieve the parameters of an existing record excluding the password.
recordId="168351" # Record ID
record=$(curl -s $auth $url/rest/record/get/$recordId)
recordname=$(echo $record | jq -r '.name')
check_status "Failed to unlock record"
recorduser=$(get_custom "$record" "User")
check_status "Failed to parse response"
echo $recordname: $recorduser
echo $record
echo Done
Retrieve a Record with Password (Unlock)
Provides the ability to retrieve the parameters of an existing record including the password.
recordId="168351" # Record ID
record=$(curl -s $auth $url/rest/record/unlock/$recordId)
recordname=$(echo $record | jq -r '.name')
check_status "Failed to unlock record"
recorduser=$(get_custom "$record" "User")
recordpassword=$(get_custom "$record" "Password")
check_status "Failed to parse response"
echo $recordname: $recorduser / $recordpassword
echo Done
Retrieve a Record Field (Unlock)
Provides the ability to retrieve a single parameter from a record’s field including the password.
recordId="168351" # Record ID $field="Password" # The (internal) Name of the field record=$(curl -s $auth $url/rest/record/unlock/$recordId/$field) check_status "Failed to unlock record" recorduser=$(get_custom "$record" "User") recordpassword=$(get_custom "$record" "Password") check_status "Failed to parse response" echo $field: $record echo Done
Update a Record
Provides the ability to update an existing record.
recordId="183323" # Record ID recordName="Updated Name" # Updated Record Name recordDescription="Updated Description" # Updated Record Description rhost="host1.company.com" # Updated Host URL rport="3389" # Updated Host Port ruser="user1" # Updated Host User rpassword="myPassw0rd1" # Updated Host Password rparameters={\"Host\":\"$rhost\",\"Port\":\"$rport\",\"User\":\"$ruser\",\"Password\":\"$rpassword\"} curl -s $auth -H "Accept: application/json" -H "Content-Type:application/x-www-form-urlencoded" -H "X-XSRF-TOKEN: $apitoken" -X PUT \ --data "name=$recordName&description=$recordDescription" \ --data-urlencode "custom=$rparameters" \ $url/rest/record/update/$recordId echo Done
Download a File
Provides the ability to download a file (certificate, SSH key, secured file) associated to a record.
recordId="183323" # Record ID fieldName="Cert" # Internal Name of Field that contains the file curl -O -J $auth $url/rest/content/record/$recordId/$fieldName echo Done
Share a Record or Folder
Provides the ability to share a record or folder with other users or groups.
shareUser="user" # Share object with User or Group Login shareUserParam=$(curl -s $auth $url/rest/user/ensure/$shareUser) shareUserId=$(echo $shareUserParam | jq -r '.id') objectId="186460" # Record or Folder ID to Share userId=$shareUserId recordControl="View" # Permission Options: View / Unlock / Edit / Admin sessionControl="None" # Permission Options: None / Recording / Connect taskControl="None" # Permission Options: None / Execute / Review / Manage curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X POST -d "" $url/rest/permissions/share/$objectId/$userId/$recordControl/$sessionControl/$taskControl echo Done
Delete a Record
Provides the ability to delete an existing record.
recordId="186008" # ID of Record to Delete folderId="183320" # Parent Folder ID curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X DELETE $url/rest/record/delete/$folderId/$recordId echo Done
Search for Objects (Record or Folder)
Provides the ability to search for existing objects, like records or folders, using search query types.
A list of query types can be found here and will allow you to target specific objects like folders, ACLs or shadow accounts. For example, if you use the search term folder:Production, it will return all folders found using the term Production.
searchTerm="object name" # Value to Search searchTerm=${searchTerm// /%20} results=$(curl -s $auth -X GET $url/rest/record/find/View/$searchTerm) searchResults=$(echo $results | jq '.[] | .name, .id') echo Results: echo $searchResults # Displays results as "Object Name" Object ID #echo $results # Displays all parameters of Objects returned in results echo Search Complete
List Record Types
Provides the ability to output a list of all currently available Record Types.
recordTypes=$(curl -s $auth -X GET $url/rest/recordtype/list)
recordTypeNamesId=$(echo $recordTypes | jq '.[] | .name, .id')
echo $recordTypeNamesId # Output as "Record Type Name" Record Type ID
echo Done
Database Export (Decrypted)
Provides the ability to output a list of all currently available Record Types.
curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X PUT $url/rest/application/export/false echo Done
Database Export (Encrypted)
Provides the ability to output a list of all currently available Record Types.
curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X PUT $url/rest/application/export/true echo Done
Database Import
Provides the ability to output a list of all currently available Record Types.
exportName="xtamexp-20180313152316-120" # Export file name
curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X PUT $url/rest/application/import/$exportName
echo Done
API Token
To provide protection against Cross-Site Request Forgery (CSRF) attacks each XTAM API function that changes something in the system (mostly, POST, PUT and DELETE REST methods) requires an API Token passed using X-XSRF-TOKEN header. To obtain a token, an XTAM REST client has to request it from XTAM server by calling /rest/user/whoami function that sets XSRF-TOKEN cookie with the value of the token. Below is the example of Shell function that obtains the API token from XTAM server by the server base URL and authentication string. See examples of using this token in the code samples above.
function api_token { base=${1} auth=${2} whoami=$(curl -D whoami.tmp -s $auth $base/user/whoami) apitoken=$(cat whoami.tmp | grep "Set-Cookie" |cut -c 13- | cut -d "=" -f 2 | cut -d ";" -f 1) rm whoami.tmp echo $apitoken }
API token enforcement could be disabled by defining parameter xtam.api.token.verification=false
Secure Authentication
XTAM provides several methods for authenticating, first is a standard, non-federated username and password login, the second is a form-based login method, the third is a more robust federated login experience that supports multi-factor authentication and additional options and the fourth is using Authentication Tokens. Depending on how your XTAM installation is configured, the following authentication methods will be used.
If your login experience to XTAM is a simple prompt like the one shown below, then you will use the following to authenticate using our REST APIs.
#!/bin/bash cookies=$(mktemp) curl_opts="-s" function cleanup { rm -f ${cookies} } trap cleanup EXIT function check_exe() { which "$1" >/dev/null 2>&1 if [ "$?" -ne 0 ]; then (>&2 echo "Required executable [$1] not found. Please install it using system package manager.") (>&2 echo "Exiting.") exit 1 fi } function check_status() { if [ $? != 0 ]; then echo $1 exit 1 fi } function cas_auth { base=${1} cas_base=${2} username=${3} password=${4} # get TGT ticket from Location header tgt_location=$(curl ${curl_opts} -X POST -D - ${cas_base}/v1/tickets -d "username=${username}" -d "password=${password}" | grep "^Location" | cut -d":" -f 2- | tr -d \\r\\n) if [ -z "${tgt_location}" ]; then (>&2 echo "CAS authentication failed: unable to obtain TGT ticket") exit 1 fi # get service ticket from TGT service_ticket=$(curl ${curl_opts} -X POST ${tgt_location} -d "service=${base}/") if [ -z "${service_ticket}" ]; then (>&2 echo "CAS authentication failed: unable to exchange TGT to service ticket") exit 1 fi # write session cookie to file curl $curl_opts --cookie-jar ${cookies} $base/?ticket=$service_ticket # print curl auth string to stdout echo "--cookie ${cookies}" } function get_custom { record=$1 field=$2 echo $record | jq -r ".custom | fromjson | .${field}" } check_exe curl check_exe jq url="https://xtam.company.com/xtam" # XTAM URL user="admin" # XTAM User #password="myPassw0rd" # Optionally define your XTAM User's Password read -p "Enter $user password: " -s password # Prompt for XTAM User's Password echo auth="-u $user:$password" # Your code starts here
If your login experience to XTAM is a form-based login page like the one shown below, then you will use the following to authenticate using our REST APIs.
url="https://xtam.company.com/xtam" # XTAM URL user="admin" # XTAM User #password="myPassw0rd" # Optionally define your XTAM User's Password tc=$(mktemp) cookies=$(mktemp) curl -s -X GET -c ${tc} -D - ${base}/rest/user/whoami > /dev/null curl -s -X POST -b ${tc} -c ${cookies} -D - ${base}/j_security_check -d "j_username=${username}" -d "j_password=${password}" > /dev/null auth="-b ${cookies}" # Your code starts here
If your login experience to XTAM is a federated sign-in page like the one shown below, then you will use the following to authenticate using our REST APIs.
#!/bin/bash cookies=$(mktemp) curl_opts="-s" function cleanup { rm -f ${cookies} } trap cleanup EXIT function check_exe() { which "$1" >/dev/null 2>&1 if [ "$?" -ne 0 ]; then (>&2 echo "Required executable [$1] not found. Please install it using system package manager.") (>&2 echo "Exiting.") exit 1 fi } function check_status() { if [ $? != 0 ]; then echo $1 exit 1 fi } function cas_auth { base=${1} cas_base=${2} username=${3} password=${4} # get TGT ticket from Location header tgt_location=$(curl ${curl_opts} -X POST -D - ${cas_base}/v1/tickets -d "username=${username}" -d "password=${password}" | grep "^Location" | cut -d":" -f 2- | tr -d \\r\\n) if [ -z "${tgt_location}" ]; then (>&2 echo "CAS authentication failed: unable to obtain TGT ticket") exit 1 fi # get service ticket from TGT service_ticket=$(curl ${curl_opts} -X POST ${tgt_location} -d "service=${base}/") if [ -z "${service_ticket}" ]; then (>&2 echo "CAS authentication failed: unable to exchange TGT to service ticket") exit 1 fi # write session cookie to file curl $curl_opts --cookie-jar ${cookies} $base/?ticket=$service_ticket # print curl auth string to stdout echo "--cookie ${cookies}" } function get_custom { record=$1 field=$2 echo $record | jq -r ".custom | fromjson | .${field}" } check_exe curl check_exe jq url="https://xtam.company.com/xtam" # XTAM URL cas_url="https://xtam.company.com/cas" # XTAM Signin Page URL user="admin" # XTAM User #password="myPassw0rd" # Optionally define your XTAM User's Password read -p "Enter $user password: " -s password # Prompt for XTAM User's Password echo auth=$(cas_auth $url $cas_url $user $password) # Your code starts here
If you are using Authentication Tokens, then you will use the following to authenticate using our REST APIs.
#!/bin/bash cookies=$(mktemp) curl_opts="-s" function cleanup { rm -f ${cookies} } trap cleanup EXIT function check_exe() { which "$1" >/dev/null 2>&1 if [ "$?" -ne 0 ]; then (>&2 echo "Required executable [$1] not found. Please install it using system package manager.") (>&2 echo "Exiting.") exit 1 fi } function check_status() { if [ $? != 0 ]; then echo $1 exit 1 fi } function token_auth { base=${1} cas_base=${2} token=${3} # get service ticket from TGT hdr=$(curl -si "${cas_base}/login?service=${base}/" -H "token:${token}" | grep "^Location") service_ticket=$(echo ${hdr} | cut -d"=" -f 2- | tr -d \\r\\n) if [ -z "${service_ticket}" ]; then (>&2 echo "CAS authentication failed: unable to exchange token to service ticket") exit 1 fi # write session cookie to file curl $curl_opts --cookie-jar ${cookies} $base/?ticket=$service_ticket # print curl auth string to stdout echo "--cookie ${cookies}" } function get_custom { record=$1 field=$2 echo $record | jq -r ".custom | fromjson | .${field}" } check_exe curl check_exe jq url="https://xtam.company.com/xtam" # XTAM URL cas_url="https://xtam.company.com/cas" # XTAM Signin Page URL token="yourXTAMtoken" # XTAM Token auth=$(token_auth $url $cas_url $token) # Your code starts here