Authentication
IAM tokens, API keys, and service tokens for the Hanzo PaaS API
Hanzo PaaS has three credential types, matched to its two API surfaces. Machine credentials are stored in Hanzo KMS and read at runtime — never hard-coded.
| Credential | Header | Surface | Use |
|---|---|---|---|
| IAM token | Authorization: Bearer <jwt> | /api | Interactive / user access via SSO |
| API key | x-api-key: <key> | /api | Machine access to the build pipeline; org-scoped |
| Service token | Authorization: Bearer <token> | /v1 | Container redeploy and observe (M2M) |
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_STATEHandle 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.
API keys (build pipeline)
API keys authenticate machine callers to the /api build-pipeline surface. Create one in the Studio under Settings → API Keys — the key is scoped to the organization you create it under and shown once.
Store API keys in Hanzo KMS immediately. They are shown only at creation. If lost, revoke and create a new one.
curl https://platform.hanzo.ai/api/application.all \
-H "x-api-key: $PLATFORM_API_KEY"Service tokens (/v1 surface)
The canonical /v1 control surface (container redeploy, /v1/apps observe) uses a service token presented as a bearer:
curl -fsS -X POST \
"https://platform.hanzo.ai/v1/org/$ORG_ID/project/$PROJECT_ID/env/$ENV_ID/container/$CONTAINER_ID/redeploy" \
-H "Authorization: Bearer $PAAS_SERVICE_TOKEN"The service token is issued out-of-band and stored in KMS (e.g. kms.hanzo.ai/v1/kms/orgs/hanzo/secrets/paas/SERVICE_TOKEN). It is a pure machine-to-machine credential with no user session.
Request examples
# List organizations (build pipeline, API key)
curl https://platform.hanzo.ai/api/organization.all \
-H "x-api-key: $PLATFORM_API_KEY"
# Register an application
curl -X POST https://platform.hanzo.ai/api/application.create \
-H "x-api-key: $PLATFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "web", "environmentId": "'$ENV_ID'" }'How is this guide?
Last updated on