REST API
All of Relution’s functionality is available through an extensive REST API. This API can be used to control Relution from any other application or via scripts.
API Documentation
Every Relution server ships the complete API specification, matching exactly the installed server version. It documents all endpoints with their parameters, request and response bodies, and the returned status codes.
The specification is opened from the Relution portal: the entry Web API in the support menu (top right corner) opens the interactive documentation. Alternatively, it is available directly at https://<server>/web-api/index.html.
Requests to the REST API are subject to the same permission checks as actions performed in the portal, and security-relevant actions are recorded in the Audit Log →.
Create API Access Tokens
To access Relution from third-party systems or scripts, an API Access Token is required.

- Clicking the username in the upper right corner of the Relution portal opens the user menu.
- The token is created under
Profile→Access tokens→Add. - The token is given a name and copied.
The following options are also available when creating a token:
- Expiration Date: mandatory, preset to today plus the default lifetime (default: 30 days). For the usage API, there is no Limited time of use switch; an API token always expires. As of Relution 27.0.1, the lifetime is also capped (default: 1 year from creation). Below the field, the dialog shows the latest possible expiration date (“The latest possible expiration date is …”); with the default, this is today plus 364 days. The dialog rejects a later date with the message “The set date must be equal or earlier than …”. The date cannot be changed after creation, and the Edit Access Token action is locked for API tokens. For a longer lifetime, a new token is created.
- API scopes: The token can only be used for requests to endpoints of the selected scopes (multiple selection, default: Management portal). The examples in this article use endpoints under
/api/management/and require this scope. A token only receives API scopes that the login creating it is valid for. If the portal session dates from before API scopes were introduced, Relution requires logging in again before a token can be created.
If an API token is created through the REST API without an expiration date, the server applies the default lifetime from relution.security.access-token.default-lifetime in application.yml (default: 30 days, minimum 1 minute). API tokens created without an expiration date before Relution 26.5.5 received an expiration date 30 days after the update.
As of Relution 27.0.1, API tokens are subject to a maximum lifetime set by relution.security.access-token.max-lifetime (default: 1 year from creation, minimum 1 minute, environment variable RELUTION_SECURITY_ACCESSTOKEN_MAXLIFETIME). For the REST API, this means:
- When a token is created, the server rejects an expiration date beyond the maximum lifetime with HTTP 422; it does not shorten it.
- When an API token is edited,
expirationDatemay be omitted or contain the stored date. The server answers a different date with HTTP 422; previously, it was silently ignored. - The endpoint
GET /api/management/v1/security/accessTokens/settingsreturns the applicable values in milliseconds (defaultLifetimeMillis,maxLifetimeMillis) to every logged-in user.
The default lifetime must not exceed the maximum lifetime, otherwise the server does not start. If max-lifetime is set below 30 days, default-lifetime therefore has to be set to the same value or lower. Existing tokens with a later expiration date remain valid, even after the maximum is lowered later on.
The token is passed in the X-User-Access-Token HTTP header to authenticate requests. As of Relution 26.5.8, the server answers requests with an expired token with HTTP 401 and the error code ACCESS_TOKEN_EXPIRED (previously HTTP 500).
As of Relution 26.5.5, HTTP Basic authentication is disabled by default, and an Authorization: Basic header is ignored. Scripts that still send a username and password are switched to access tokens. Only as a temporary measure can Basic authentication be re-enabled via relution.security.basic-auth.enabled: true.
A request authenticated with an access token is subject to the following restrictions; in each case, the server responds with HTTP 403:
- It cannot create a new access token.
- It can only narrow the API scopes of a token, not widen them.
- It does not receive a portal session, neither through login, multi-factor authentication nor impersonation.
New tokens are therefore created in the portal or with a regular login, not from a script that authenticates itself with a token.
Administrators with the permission to create API access tokens can also create a token for another user, for example for a service account. To do so, exactly one user is selected under Users → Users and the action Add Access Token is called from the context menu.
1. Users in CSV File Format
- The first line of the
.csvfile contains a header line with the desired property names. - The order of the columns is not relevant.
- Properties that are not needed can be omitted.
- Mandatory fields: The header line must contain the
emailcolumn, and every row needs a user name in thenamecolumn. The portal template starts with the following columns:
name,email,givenName,surname,password
Column names are not case-sensitive. Passwords must follow the policy under Settings → Login Management. Phone numbers must be in international format, e.g. +4912345.
Up to 15 custom properties can be added, named:
custom1 – custom15
The portal template contains further columns, such as disablePasswordAuthentication, locale, permissions, memberOfGroups, teacherOfClasses and studentOfClasses. Their meaning is described in the article CSV Import →.
👉 A template can be downloaded in the Relution portal:
Users → Users → Three dots menu → Import users via CSV. In the dialog, it is available via the template link in the description text.
Example CSV:
name,email,givenName,surname,password,phone,position,country,managedAppleId,custom1,custom2
user1,user1@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user1 position,user1 country,user1.id@company.com,43,Operations
user2,user2@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user2 position,user2 country,user2.id@company.com,24,Marketing
user3,user3@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user3 position,user3 country,user3.id@company.com,30,HR
user4,user4@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user4 position,user4 country,user4.id@company.com,32,Sales
user5,user5@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user5 position,user5 country,user5.id@company.com,45,Finance
user6,user6@company.com,Heinz,Ketchup,p4ssw0rd,+49234346345,user6 position,user6 country,user6.id@company.com,30,Purchase
2. Uploading Users via the Relution Portal
- The import is opened via
Users→Users→Three dots menu→Import users via CSV. - The CSV file and the separator are selected. The option Automatically create groups and classes creates groups and classes that are named in the file but do not exist yet.
- The imported users can be assigned to one or more groups.
- Imported users will then appear in the overview.
3. Creating Users via the Relution API
Relution 5.34 change:
- User import is now a background job with the states CREATED, RUNNING, FINISHED and FAILED.
- Each job stores a report per line.
- Legacy import was removed.
- Some column names changed:
first name→givenNamelast name→surnamemanaged apple id→managedAppleIdphone number→phoneuserId→name
Steps
A
users.csvfile is prepared.The bash script below is copied into a file, e.g.
uploadUserCSV.sh.The file is made executable:
chmod +x ./uploadUserCSV.shThe script is then run:
./uploadUserCSV.sh -f 'FILEPATH' -h 'HOST' -a 'YOUR-ACCESS-TOKEN'
Arguments
| Argument | Meaning | Example | Default | Required |
|---|---|---|---|---|
-f | Path to the users.csv | user.csv | ✅ | |
-h | Relution host | https://relution.io | ✅ | |
-a | API access token | xxxxxxxx | ✅ | |
-r | Group (name or UUID) the imported users are assigned to; spaces as %20 | School%20Teachers | Organame%20Device%20User | ❌ |
-s | Separator for parsing | SEMICOLON | COMMA | ❌ |
-w | Overwriting existing users | true | false | ❌ |
- Users are imported into the organization of the account that owns the API access token. This account needs the permissions to create and update users.
- Without
-r, the script uses the groupOrganame Device User. “Organame” has to be replaced in the script with the name of the own organization; otherwise no group is assigned. - With
-w true, existing users are overwritten; they are matched by thenamecolumn. Users that originate from an external directory such as LDAP are skipped. - The API additionally supports the parameter
createMissingGroupsAndClasses=true. It corresponds to the portal option Automatically create groups and classes and is not set by the script.
As of Relution 27.0.1, the server ignores a hashedPassword field sent when users are created via the REST API (POST /api/management/v1/security/users). The password is only passed in plain text in the password field and must comply with the password policy. If password is missing, the server creates the user without a password. Scripts and integrations that pass precomputed hashes are switched to password.
Output Example
============
success: 1, skipped: 1, failed: 1
2: [SUCCESS] User ... successfully stored with version 1.
3: [FAILED] Number of data fields does not match number of headers.
4: [SKIPPED] User Test2 should not be overwritten.
4. Bash Script: Upload Users via CSV
Show full configuration example
#!/bin/bash
set -e
# --------------------------------------------------------------------------------
while getopts "a:h:f:w:r:s:" opt; do
case $opt in
a) # apikey
ACCESS_TOKEN="$OPTARG"
;;
h) # host
HOST="$OPTARG"
;;
f) # File
FILE="$OPTARG"
;;
w) # Overwrite
OVERWRITE="$OPTARG"
;;
r) # Group (name or UUID)
ROLE="$OPTARG"
;;
s) # Separator
SEPARATOR="$OPTARG"
;;
\?)
echo "Unknown option -$OPTARG" >&2
;;
esac
done
if [[ -z $ACCESS_TOKEN ]]; then
echo "Please specify an access token (-a)"
exit 1
fi
if [[ -z $HOST ]]; then
echo "Please specify a Host URL (-h)"
exit 1
fi
if [[ ! -f $FILE ]]; then
echo "Please specify an existing csv file (-f)"
exit 1
fi
if [[ -z $SEPARATOR ]]; then
SEPARATOR="COMMA"
fi
if [[ -z $OVERWRITE ]]; then
OVERWRITE=false
fi
if [[ -z $ROLE ]]; then
ROLE=Organame%20Device%20User
fi
call() {
# Create a temporary file for the response body
tmpfile=$(mktemp) || { echo "Failed to create temp file" >&2; exit 1; }
http_code=$(curl -sw "%{http_code}" -o "$tmpfile" -H "Accept: application/json" -H "X-User-Access-Token: $ACCESS_TOKEN" "$@")
content=$(cat "$tmpfile")
rm -f "$tmpfile"
if [[ "$http_code" != "200" && "$http_code" != "201" ]]; then
echo "fail: $http_code" >&2
echo $content >&2
exit 1
fi
# Output the content for capture
printf "%s" "$content"
}
echo "Will start importing users on server '${HOST}' into group '${ROLE//%20/ }'."
echo "Using '$FILE' with separator of type '$SEPARATOR'."
echo "Next step: uploading file"
upload=$(call -F "file=@$FILE;type=text/csv" "$HOST/api/management/v1/csvImport/upload/users")
file_uuid=$(echo "$upload" | jq -r '.results[0].uuid')
echo "Done uploading file: $file_uuid"
echo "============"
echo "Next step: start import job"
job=$(call -X POST "$HOST/api/management/v1/security/users/import/fromFile/$file_uuid?overwrite=$OVERWRITE&role=$ROLE&csvSeparator=$SEPARATOR")
job_uuid=$(echo "$job" | jq -r '.uuid')
echo "Job started: $job_uuid"
job_status=""
while [[ "$job_status" != "FINISHED" && "$job_status" != "FAILED" ]]; do
sleep 1
job=$(call -X GET "$HOST/api/management/v1/csvImport/job/$job_uuid")
job_status=$(echo "$job" | jq -r '.results[0].status')
echo "Job status: $job_status"
done
echo "============"
success_count=$(echo "$job" | jq -r '.results[0].successCount')
skipped_count=$(echo "$job" | jq -r '.results[0].skippedCount')
failure_count=$(echo "$job" | jq -r '.results[0].failureCount')
echo "success: $success_count, skipped: $skipped_count, failed: $failure_count"
if [[ "$failure_count" -ne 0 ]]; then
query='{"sortOrder":{"sortFields":[{"name":"line","ascending":true}]}}'
report=$(call -X POST -H "Content-Type: application/json" --data "$query" "$HOST/api/management/v1/csvImport/job/$job_uuid/entityStates/query")
reports=$(echo $report | jq -c '.results')
echo "$reports" | jq -c '.[]' | while read -r item; do
line=$(echo "$item" | jq -r '.line')
status=$(echo "$item" | jq -r '.status')
message=$(echo "$item" | jq -r '.message')
echo "$line: [$status] $message"
done
fi
5. Create a New Organization
The following script creates a new organization including an organization administrator. The token used belongs to a user with the permission to create organizations or sub-organizations, for example the system administrator. The short name orgaName is required; the administrator details (orgaAdminUser, orgaAdminGivenName, orgaAdminSurName, orgaAdminPwd) are required as long as skipAdminCreation is not set to true. The administrator password must meet the default password policy. On success, the server responds with HTTP status 202 and returns the UUID of the organization, its name and the UUID of the administrator.
Show full configuration example
#!/bin/bash
#--------------------------------------------------------------------------------
# Web service URL, change the server name as needed
SVR_URL="https://<myserver>/api/management/v1/security/organizations/creationWizardRequests"
# Access token of a user who is allowed to create organizations or sub-organizations
# (e.g. the system administrator). Create it via the user menu in the top right corner
# of the portal: "Profile", "Access tokens", "Add".
ACCESS_TOKEN="<sysadmin_api_token>"
# HTTP Headers
ACCEPT="application/json"
ACCEPT_CHARSET="UTF-8"
# Organization and administrator data
# "orgaName" is required. The "orgaAdmin..." fields are required unless "skipAdminCreation" is true.
# The administrator password must meet the default password policy.
read -r -d '' JSON_BODY << 'EOF'
{
"orgaName": "neworg",
"orgaFullName": "New Organization Ltd.",
"orgaLocale": "en_US",
"orgaAdminUser": "neworg-admin",
"orgaAdminGivenName": "Max",
"orgaAdminSurName": "Mustermann",
"orgaAdminEmail": "admin@example.com",
"orgaAdminPwd": "<password>"
}
EOF
echo "Creating organization at $SVR_URL..."
echo
# No changes should be required beyond this line...
RESPONSE=$(curl -X POST \
"${SVR_URL}" \
-H "X-User-Access-Token: $ACCESS_TOKEN" \
-H "Accept: $ACCEPT" \
-H "Accept-Charset: $ACCEPT_CHARSET" \
-H "Content-Type: $ACCEPT" \
--write-out " HTTP_STATUS=%{http_code}" \
--silent \
-d "$JSON_BODY")
if [[ $RESPONSE =~ HTTP_STATUS=([0-9]+) ]]; then
HTTP_STATUS=${BASH_REMATCH[1]}
fi
if [[ $HTTP_STATUS -lt 200 || $HTTP_STATUS -gt 299 ]]; then
echo "HTTP status: $HTTP_STATUS"
echo "${RESPONSE%HTTP_STATUS*}"
else
echo "Done. Parsing output..."
echo
echo "${RESPONSE%HTTP_STATUS*}" | jq '{orgaId, orgaName, orgaAdminId}'
fi
6. Query Devices in an Organization
Show full configuration example
#!/bin/bash
#--------------------------------------------------------------------------------
# Web service URL, change the server name as needed
SVR_URL="https://<myserver>/api/management/v2/devices/baseInfo/query"
# Access token of an Orga Admin, create it by clicking on the user name in the top right corner of the portal.
# Then click "Profile", "Access tokens", "Add".
ACCESS_TOKEN="<orga_admin_access_token>"
# HTTP Headers
ACCEPT="application/json"
ACCEPT_CHARSET="UTF-8"
# Query example
read -r -d '' JSON_BODY << 'EOF'
{
"limit": 100,
"offset": 0,
"getNonpagedCount": true,
"sortOrder": {
"sortFields": [
{
"name": "lastConnectionDate",
"ascending": false
}
]
},
"filter": {
"type": "logOp",
"operation": "AND",
"filters": [
{
"type": "stringEnum",
"fieldName": "platform",
"values": [
"ANDROID",
"ANDROID_ENTERPRISE",
"IOS"
]
},
{
"type": "stringEnum",
"fieldName": "status",
"values": [
"COMPLIANT"
]
}
]
}
}
EOF
echo "Querying devices at $SVR_URL..."
echo
# No changes should be required beyond this line...
RESPONSE=$(curl -X POST \
"${SVR_URL}" \
-H "X-User-Access-Token: $ACCESS_TOKEN" \
-H "Accept: $ACCEPT" \
-H "Accept-Charset: $ACCEPT_CHARSET" \
-H "Content-Type: $ACCEPT" \
--write-out " HTTP_STATUS=%{http_code}" \
--silent \
-d "$JSON_BODY")
if [[ $RESPONSE =~ HTTP_STATUS=([0-9]+) ]]; then
HTTP_STATUS=${BASH_REMATCH[1]}
fi
if [[ $HTTP_STATUS -lt 200 || $HTTP_STATUS -gt 299 ]]; then
echo "HTTP status: $HTTP_STATUS"
else
echo "Done. Parsing output..."
echo "${RESPONSE%HTTP_STATUS*}" | jq '.results[].name'
fi
echo
API Token Best Practices
- The lifetime of API access tokens should be as short as the use case allows. Relution enforces an expiration date and, as of Relution 27.0.1, caps the lifetime at 1 year. A shorter maximum can be enforced on the server via
relution.security.access-token.max-lifetime. - Tokens should be revoked immediately when the associated account’s role changes, the account is deactivated, or the account holder leaves the organization.
- If an account is locked or deactivated, its API tokens are suspended for as long as the lock lasts (HTTP 403). After unlocking, they work again. A password change does not revoke API tokens. Revoking therefore remains the reliable way to make a token permanently unusable.
- Token secrets are stored only as hashes (SHA-256, or HMAC-SHA-256 if an HMAC key is configured) and cannot be recovered after creation. When needed, a new token is generated rather than attempting to retrieve an existing one.
Related Topics
- Create API access tokens in Relution → — Instructions for generating tokens.
- LDAP / Active Directory connection → — Synchronization of users and groups.