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.

Add new access token dialog with expiration date and API scopes

  1. Clicking the username in the upper right corner of the Relution portal opens the user menu.
  2. The token is created under Profile → Access tokens → Add.
  3. 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, expirationDate may 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/settings returns 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.

The token will only be displayed once when it is created.

1. Users in CSV File Format

  • The first line of the .csv file 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 email column, and every row needs a user name in the name column. 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

  1. The import is opened via Users → Users → Three dots menu → Import users via CSV.
  2. 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.
  3. The imported users can be assigned to one or more groups.
  4. 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 → givenName
    • last name → surname
    • managed apple id → managedAppleId
    • phone number → phone
    • userId → name

Steps

  1. A users.csv file is prepared.

  2. The bash script below is copied into a file, e.g. uploadUserCSV.sh.

  3. The file is made executable:

    chmod +x ./uploadUserCSV.sh
    
  4. The script is then run:

./uploadUserCSV.sh -f 'FILEPATH' -h 'HOST' -a 'YOUR-ACCESS-TOKEN'

Arguments

ArgumentMeaningExampleDefaultRequired
-fPath to the users.csvuser.csv✅
-hRelution hosthttps://relution.io✅
-aAPI access tokenxxxxxxxx✅
-rGroup (name or UUID) the imported users are assigned to; spaces as %20School%20TeachersOrganame%20Device%20User❌
-sSeparator for parsingSEMICOLONCOMMA❌
-wOverwriting existing userstruefalse❌
  • 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 group Organame 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 the name column. 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.

How helpful was this article?