Authenticating to the Client Portal API

Obtaining a token

The API uses short-lived bearer tokens issued to a service account. Service accounts are created in the Client Portal under Access, and their scopes are defined at creation rather than with each request.

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 sparingly. A service account with write access can decommission a server, which permanently erases its storage.

Rotation

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

To rotate without downtime, create the replacement secret, deploy it, confirm that traffic is using it, and then revoke the previous secret. Both secrets remain valid during the transition.

Handling common errors

• 401 with token_expired. Request a new token and retry once. Avoid repeated immediate retries.
• 403 with scope_insufficient. The service account does not have the required scope. Retrying will not resolve this error.
• 409 on a provisioning call. The server is changing state. Check its status rather than resubmitting the request.
• 429. Back off using the Retry-After header. Rate limits apply per service account, not per boundary.

Every request within your boundary is recorded in the audit log, including failures. Assessors frequently review failed authorization attempts, so use clear, descriptive service account names.