Management API and Machine Tokens

Management endpoints live under /api/organizations/:orgSlug/*. Use machine tokens for automation so deployments, provisioning jobs, and CI do not depend on personal browser sessions.

Authentication Choices

Create machine tokens from the app settings UI whenever possible (recommended).
You can also create them from an authenticated admin session if you are bootstrapping automation.
Use the narrowest scope that still lets the job succeed.

Create a Machine Token

Bash

API_BASE_URL="https://api.errova.com/api"
ORG_SLUG="acme-inc"

curl -sS -X POST "${API_BASE_URL}/organizations/${ORG_SLUG}/machine-tokens" \
  -H "Content-Type: application/json" \
  -H "Origin: https://errova.com" \
  -H "Referer: https://errova.com/" \
  -b "errova_session=<session_cookie_value>" \
  --data '{"label":"CI deploy token","scopes":["org.admin"]}'

The returned tokenSecret is shown once. Store it immediately and treat it like any other production secret.

Use the Token for Project and DSN Operations

Bash

MACHINE_TOKEN="<tokenSecret>"
PROJECT_SLUG="web-app"

curl -sS -X POST "${API_BASE_URL}/organizations/${ORG_SLUG}/projects" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  --data '{"name":"Web App","platform":"nextjs","environment":"production"}'

curl -sS -X POST "${API_BASE_URL}/organizations/${ORG_SLUG}/projects/${PROJECT_SLUG}/keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  --data '{"label":"backend ingest","keyType":"server_signed"}'

Rotate or Revoke Machine Tokens

Bash

MACHINE_TOKEN="<tokenSecret_from_create_response>"
TOKEN_ID="<machine_token_id>"

curl -sS -X POST "${API_BASE_URL}/organizations/${ORG_SLUG}/machine-tokens/${TOKEN_ID}/rotate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  --data '{}'

curl -sS -X DELETE "${API_BASE_URL}/organizations/${ORG_SLUG}/machine-tokens/${TOKEN_ID}" \
  -H "Authorization: Bearer ${MACHINE_TOKEN}"

Expire or Rotate DSN Keys

Bash

KEY_ID="<dsn_key_id>"
EXPIRES_AT="$(date -u -v+30d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '+30 days' +%Y-%m-%dT%H:%M:%SZ)"

curl -sS -X PATCH "${API_BASE_URL}/organizations/${ORG_SLUG}/projects/${PROJECT_SLUG}/keys/${KEY_ID}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  --data "{\"expiresAt\":\"${EXPIRES_AT}\"}"

curl -sS -X POST "${API_BASE_URL}/organizations/${ORG_SLUG}/projects/${PROJECT_SLUG}/keys/${KEY_ID}/rotate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MACHINE_TOKEN}" \
  --data '{}'

Scope Guidance

org.read for read-only automation and inventory jobs.
org.admin for project creation, DSN key management, alert management, and other mutating workflows.
Create separate machine tokens per workload so rotation and revocation stay low-risk.
Rotate replacement credentials before revoking the old ones.