Authenticating to the Client Portal API

Obtaining a token

The API authenticates with short-lived bearer tokens issued against a service account. Service accounts are created in the Client Portal under Access, and each one is scoped when it is created rather than at request time.

curl -sS -X POST https://api.servlogi.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
        "client_id": "svc-deploy-prod",
        "client_secret": "'"$SERVLOGI_SECRET"'"
      }'

# {
#   "access_token": "...",
#   "token_type": "Bearer",
#   "expires_in": 86400,
#   "scope": "hosts:read hosts:write attestation:read"
# }

Scopes

• hosts:read lists hosts and reads their state.
• hosts:write provisions, modifies, and decommissions hosts.
• attestation:read retrieves attestation reports.
• billing:read reads allocation and usage records.
• audit:read reads the audit log for your boundary.

Grant hosts:write narrowly. A service account with write scope can decommission a host, and decommissioning triggers irreversible media sanitization.

Rotation

Tokens expire after 24 hours and are not refreshed automatically. Client secrets do not expire on a schedule, but rotating them at least every 90 days is expected and is checked during assessment.

Rotate without downtime by creating the replacement secret, deploying it, confirming traffic has moved, and only then revoking the old one. Both secrets are valid during the overlap.

Failure modes worth handling

• 401 with token_expired. Re-issue and retry once. Do not retry in a tight loop.
• 403 with scope_insufficient. The service account lacks the scope. Retrying will not help.
• 409 on a provisioning call. The host is mid state transition. Poll state rather than resubmitting.
• 429. Back off using the Retry-After header. The limit is per service account, not per boundary.

Every request against your boundary is recorded in the audit log, including failures. Requests that fail authorization are exactly the ones an assessor will ask about, so keep service account naming meaningful.