Authentication

Authentication

The API uses OAuth 2.0 client credentials. Every request (except the token endpoint itself) requires a valid bearer token in the Authorization header.

Your administrator provides a client ID and secret.

POST /Token

curl -X POST https://your-host/api/v2/Token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni...",
  "token_type": "bearer",
  "expires_in": 14399
}

The token is valid for 4 hours. Request a new token before the current one expires.

You can also authenticate using HTTP Basic (-u "CLIENT_ID:SECRET") instead of form fields.

Using the Token

Include the token in all subsequent requests:

curl https://your-host/api/v2/Item?page=1&pageSize=10 \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1Q..."

PowerShell

$tokenResponse = Invoke-RestMethod -Uri "https://your-host/api/v2/Token" `
    -Method Post `
    -Body @{
        grant_type    = "client_credentials"
        client_id     = "YOUR_CLIENT_ID"
        client_secret = "YOUR_CLIENT_SECRET"
    }
$token = $tokenResponse.access_token

# Use the token in subsequent requests
$items = Invoke-RestMethod -Uri "https://your-host/api/v2/Item?page=1&pageSize=10" `
    -Headers @{ Authorization = "Bearer $token" }

Token Lifecycle

Authorization

Authentication is the primary access gate — a valid bearer token is required for every endpoint. Every endpoint also enforces action permissions. Each resource requires a specific permission (Security ID); if your integration user’s group lacks it, the API returns 403 Insufficient permissions. Accounts marked read-only receive 403 on all write verbs. Operations are additionally scoped to warehouses assigned to your integration user; writes to unassigned warehouses return 403. Unauthenticated requests return 401.

• Action permissions — each endpoint requires a specific security permission. If the group doesn’t grant it, you get HTTP 403.
• Warehouse scope — writes are limited to the warehouses assigned to your integration user; writing to any other warehouse returns 403. Read endpoints are not warehouse-scoped.
• Read-only mode — if the user is marked read-only, all POST/PUT/DELETE requests return 403.
• Report access — the Reports endpoint respects report-level permissions from the user’s group.

Required permissions per endpoint

Security Notes

• Never embed credentials in client-side code or public repositories
• Use HTTPS exclusively — credentials sent over HTTP are rejected
• Rotate secrets periodically through your administrator
• Each integration should use its own credentials — don’t share across systems