Authentication

Hanzo PaaS has one API surface — https://api.hanzo.ai/v1/platform — and one credential shape: a bearer token. Machine credentials live in Hanzo KMS and are read at runtime, never hard-coded.

Credential	Header	Use
IAM token	`Authorization: Bearer <jwt>`	Everything — interactive SSO and machine access. An org-admin IAM login also authorizes `POST /v1/runner` builds.
Build token	`Authorization: Bearer <build-token>`	Fabric automation only (git-push-to-deploy, self-release). Never held by a user.

There is no x-api-key header and no separate service token.

OAuth2 via Hanzo ID

Interactive access uses the Hanzo ID OAuth2 Authorization Code flow.

Redirect to Hanzo ID

https://hanzo.id/v1/iam/oauth/authorize?
  client_id=hanzo-platform&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid profile email&
  state=RANDOM_STATE

Handle the callback

Hanzo ID redirects back with ?code=...&state=....

Exchange the code for tokens

curl -X POST https://hanzo.id/v1/iam/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "hanzo-platform",
    "client_secret": "'$CLIENT_SECRET'",
    "code": "'$AUTH_CODE'",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code"
  }'

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

Refresh with grant_type=refresh_token. See Hanzo IAM for the full flow.

Machine identity (no user present)

A service exchanges its KMS machine identity for the same kind of bearer — no second credential type, no key file:

TOKEN=$(curl -sS -X POST https://api.hanzo.ai/v1/kms/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r .accessToken)

clientId / clientSecret come from a Kubernetes Secret or your secret store — never inline them. The response is {"accessToken":"<RS256 JWT>","expiresIn":604800,"tokenType":"Bearer"}.

Request examples

# List projects
curl -fsS https://api.hanzo.ai/v1/platform/projects \
  -H "Authorization: Bearer $TOKEN"

# Create an application
curl -fsS -X POST https://api.hanzo.ai/v1/platform/projects/$PROJECT/apps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "web" }'

# Roll it forward
curl -fsS -X POST https://api.hanzo.ai/v1/platform/projects/$PROJECT/apps/web/deploy \
  -H "Authorization: Bearer $TOKEN"