Skip to main content

How to authenticate

All API calls require a valid access token and, for tenant-scoped resources, the X-Tenant-Id header.

Prerequisites​

  • User account in your CataZenta tenant
  • API base URL: https://api.catazenta.com
  • Tenant UUID (from admin or GET /v1/auth/me after first login)

Step 1 — Login​

curl -s -X POST "https://api.catazenta.com/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "YOUR_PASSWORD",
    "client_id": "pim_web"
  }'

Example response (fields may vary):

{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Store access_token in a secret manager — never commit it to git.

Step 2 — Verify identity​

curl -s "https://api.catazenta.com/v1/auth/me" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Confirm your user, roles, and tenant membership before automating writes.

Step 3 — Call tenant-scoped APIs​

export TOKEN="eyJ..."
export TENANT="your-tenant-uuid"

curl -s "https://api.catazenta.com/v1/products?page=1&page_size=5" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-Id: ${TENANT}"

Missing X-Tenant-Id on multi-tenant endpoints typically returns 403 or 400 — see API authentication.

Step 4 — Refresh tokens​

Before expires_in elapses, refresh using the endpoint documented in the IAM API. Long-running jobs should use a service account instead of a personal password.

Service accounts (CI/CD)​

For pipelines, prefer client credentials or service users — Service account recipe.

Troubleshooting​

SymptomCheck
401 UnauthorizedToken expired or wrong Authorization header
403 ForbiddenRole lacks permission; wrong tenant header
400 Bad RequestMalformed JSON or missing client_id

Next steps​