Use the ELOS API

For administrators, engineers 6 min read

Authenticate scripts with a service account key, page through results, retry safely and stay within rate limits.

Get a key

1. Create a service account for the job, for example hr-import or catalog-bot.
2. Give it the narrowest role that works. Onboarding needs Manage people and Request access; catalog updates need Edit service catalog. A custom role can limit catalog edits to specific services.
3. Copy the key when it's shown. Store it in your secrets manager or CI secrets, never in a repository.

Make a request

Send the key as a bearer token. The key identifies your workspace, so there's nothing else to set. Every request is checked against the service account's role, and every change is in the audit log under its name.

curl -sS "$ELOS_API/v1/services?q=payments&limit=50" \
  -H "Authorization: Bearer $ELOS_KEY"

Page through results

Lists are paged. Ask for up to 200 items with limit, then pass the nextCursor from each page as cursor until there's no next cursor.

cursor=""
while :; do
  page=$(curl -sS "$ELOS_API/v1/people?limit=200${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $ELOS_KEY")
  jq -r '.data[].name' <<<"$page"
  cursor=$(jq -r '.nextCursor // empty' <<<"$page")
  [ -z "$cursor" ] && break
done

Retry safely

• Send an Idempotency-Key header on every write. If a request is retried with the same key within 24 hours, ELOS returns the first response instead of doing the work twice, and marks it with Idempotency-Replayed: true.
• Use a key that's stable for the row you're importing, such as joiner-<employee-id>, so re-running a whole file is safe.
• If you get 429 Too Many Requests, wait for the time in Retry-After and try again. Send requests one at a time rather than in parallel.

Errors

Errors come back as problem details (application/problem+json) with a title and a detail.