REST API
- API-Dokumentation
- API-Zugriffstoken erstellen
- 1. Benutzer im CSV-Dateiformat
- 2. Benutzer über das Relution-Portal hochladen
- 3. Benutzer über die Relution API anlegen
- Ausgabe-Beispiel
- 4. Benutzer per CSV über Bash-Skript hochladen
- 5. Neue Organisation erstellen
- 6. Geräte in einer Organisation abfragen
- Bewährte Praktiken für API-Token
- Verwandte Themen
Auf dieser Seite
- API-Dokumentation
- API-Zugriffstoken erstellen
- 1. Benutzer im CSV-Dateiformat
- 2. Benutzer über das Relution-Portal hochladen
- 3. Benutzer über die Relution API anlegen
- Ausgabe-Beispiel
- 4. Benutzer per CSV über Bash-Skript hochladen
- 5. Neue Organisation erstellen
- 6. Geräte in einer Organisation abfragen
- Bewährte Praktiken für API-Token
- Verwandte Themen
Die gesamte Funktionalität von Relution steht über eine umfangreiche REST API zur Verfügung. Mit dieser API lässt sich Relution von jeder anderen Anwendung oder per Skript steuern.
API-Dokumentation
Jeder Relution-Server liefert die vollständige API-Spezifikation mit, passend zur installierten Server-Version. Sie dokumentiert alle Endpunkte mit ihren Parametern, Request- und Response-Bodys sowie den zurückgegebenen Statuscodes.
Die Spezifikation wird aus dem Relution-Portal geöffnet: Der Eintrag Web API im Support-Menü (oben rechts) öffnet die interaktive Dokumentation. Alternativ ist sie direkt unter https://<server>/web-api/index.html erreichbar.
Anfragen an die REST API unterliegen denselben Berechtigungsprüfungen wie Aktionen im Portal; sicherheitsrelevante Aktionen werden im Audit-Protokoll → aufgezeichnet.
API-Zugriffstoken erstellen
Um Relution von Drittsystemen oder Skripten aus anzusprechen, wird ein API-Zugriffstoken benötigt.
- Oben rechts im Relution-Portal auf den eigenen Benutzernamen klicken.
- Navigieren zu:
Profil→Zugriffstoken→Zugriffstoken hinzufügen. - Das Token benennen und kopieren.
Das Token wird im HTTP-Header X-User-Access-Token zur Authentifizierung genutzt.
1. Benutzer im CSV-Dateiformat
- In die erste Zeile der
.csv-Datei kommt eine Kopfzeile mit den gewünschten Eigenschaftsnamen. - Die Reihenfolge der Spalten ist unerheblich.
- Nicht benötigte Eigenschaften können weggelassen werden.
- Pflichtfelder:
userid,email,first name,last name,password
Passwörter müssen der Richtlinie unter Einstellungen → Passwort-Richtlinie entsprechen. Telefonnummern müssen im internationalen Format angegeben werden, z. B. +4912345.
Es können bis zu 15 eigene Eigenschaften definiert werden:
custom1 – custom15
👉 Eine Vorlage kann im Relution-Portal heruntergeladen werden:
Benutzer → Benutzer → Drei-Punkte-Menü → Benutzer per CSV importieren → Vorlage herunterladen
Beispiel-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. Benutzer über das Relution-Portal hochladen
- Aufrufen:
Benutzer→Benutzer→Drei-Punkte-Menü→Benutzer per CSV importieren - CSV-Datei und Trennzeichen auswählen.
- Importierte Benutzer einer oder mehreren Gruppen zuordnen.
- Die Benutzer erscheinen anschließend in der Übersicht.
3. Benutzer über die Relution API anlegen
Änderung in Relution 5.34:
- Der Benutzerimport läuft nun als Hintergrund-Job mit den Zuständen (RUNNING / FINISHED).
- Jeder Job speichert einen Bericht pro Zeile.
- Der alte Import wurde entfernt.
- Einige Spaltennamen wurden geändert:
first name→givenNamelast name→surNamemanaged apple id→managedAppleIdphone number→phoneuserId→name
Schritte
Eine
users.csv-Datei erstellen.Das folgende bash-Skript in eine Datei kopieren, z. B.
uploadUserCSV.sh.Die Datei ausführbar machen:
chmod +x ./uploadUserCSV.shEs ausführen:
./uploadUserCSV.sh -f 'FILEPATH' -h 'HOST' -a 'YOUR-ACCESS-TOKEN' -u 'ORGANIZATION_UUID'
Argumente
| Argument | Bedeutung | Beispiel | Standard | Pflicht |
|---|---|---|---|---|
-f | Pfad zur users.csv | user.csv | ✅ | |
-h | Relution-Host | https://relution.io | ✅ | |
-a | API-Zugriffstoken | xxxxxxxx | ✅ | |
-u | Organisations-UUID | 01995C17-6BD0-7F84-87E9-21A1498B386F | ✅ | |
-r | Benutzerrollen | Organame%20Device%20User | ❌ | |
-s | Trennzeichen zum Parsen | SEMICOLON | COMMA | ❌ |
-w | Überschreiben vorhandener Benutzer | true | false | ❌ |
Ausgabe-Beispiel
============
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. Benutzer per CSV über Bash-Skript hochladen
Vollständiges Konfigurationsbeispiel anzeigen
#!/bin/bash
set -e
# --------------------------------------------------------------------------------
while getopts "a:h:f:u:w:r:s:" opt; do
case $opt in
a) # apikey
ACCESS_TOKEN="$OPTARG"
;;
h) # host
HOST="$OPTARG"
;;
f) # File
FILE="$OPTARG"
;;
u) # organization uuid
ORGANIZATION_UUID="$OPTARG"
;;
w) # Overwrite
OVERWRITE="$OPTARG"
;;
r) # Role
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 $ORGANIZATION_UUID ]]; then
echo "Please specify an organization uuid (-o)"
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 to '${ORGANIZATION_UUID}' on server '${HOST} as '${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. Neue Organisation erstellen
Vollständiges Konfigurationsbeispiel anzeigen
#!/bin/bash
#--------------------------------------------------------------------------------
# Web service URL, change the server name as needed
SVR_URL="https://<myserver>/api/management/v1/security/organizations/creationWizardRequests"
# Access token of System Admin, create it by opening https://<server>/#/profile
# Open this URL in your browser while logged in as System Administrator.
# NOTE: This is not an URL you can reach through clicking through the portal!
ACCESS_TOKEN="<sysadmin_api_token>"
# HTTP Headers
ACCEPT="application/json"
ACCEPT_CHARSET="UTF-8"
# Query example
read -r -d '' JSON_BODY << 'EOF'
{
"limit": 10,
"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",
"INACTIVE"
]
}
]
}
}
EOF
echo "Querying devices at $SVR_URL..."
echo
# No changes should be required beyond this line...
RESPONSE=$(curl -X POST \
${SVR_URL}${FILTER} \
-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 ouput..."
echo
echo "${RESPONSE%HTTP_STATUS*}" | jq '.results[].name'
fi
6. Geräte in einer Organisation abfragen
Vollständiges Konfigurationsbeispiel anzeigen
#!/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 GET \
${SVR_URL}${FILTER} \
-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 ouput..."
echo ${RESPONSE%HTTP_STATUS*} | jq '.results[].name'
fi
echo
Bewährte Praktiken für API-Token
- Bei API-Zugriffstoken immer ein Ablaufdatum festlegen. Token ohne Ablaufdatum bleiben unbegrenzt gültig.
- Token sofort widerrufen, wenn sich die Rolle des zugehörigen Kontos ändert, das Konto deaktiviert wird oder der Kontoinhaber die Organisation verlässt.
- Token-Geheimnisse werden als BCrypt-Hashes gespeichert und können nach der Erstellung nicht wiederhergestellt werden. Bei Bedarf einen neuen Token erstellen, anstatt zu versuchen, einen bestehenden abzurufen.
Verwandte Themen
- API-Zugriffstoken in Relution erstellen → — Anleitung zur Token-Generierung.
- LDAP / Active Directory Anbindung → — Benutzer und Gruppen synchronisieren.