zitadel-api

ZITADEL API v2 (v4 GA)

Official docs: https://zitadel.com/docs/apis/v2

Architecture

ZITADEL Instance
  └── Organizations (multi-tenant units)
        └── Projects (group apps + roles)
              ├── Applications (OIDC / SAML / API clients)
              │     └── Application Keys (for API apps)
              └── Roles (custom keys: admin/viewer/editor/etc.)
                    └── Grant Assignments (user-to-role mapping)

Authentication

Who Is the Client?

All instance-level operations (create org, create project, create app, create user, role grants) require the ZITADEL IAM admin service account. This is the system's own admin user, not a regular org user. In this cluster, the credentials are stored in the zitadel namespace:

• iam-admin-pat — Personal Access Token (simpler, use first)
• iam-admin-jwt — Private Key JWT (use when PAT doesn't have enough permissions)

A regular user's PAT (from Acme, Family, or any org) can only manage resources within their own org and project. It cannot create orgs, projects, or users across the instance.

Personal Access Token (PAT)

Simplest auth. Get from the IAM admin secret:

export PAT=$(kubectl get secret iam-admin-pat -n zitadel -o jsonpath='{.data.pat}' | base64 -d)

Headers for all API calls:

-H "Authorization: Bearer ${PAT}" \
-H "Content-Type: application/json" \
-H "Connect-Protocol-Version: 1"

Service Account JWT (Private Key)

Use when PAT returns 403 on instance-level operations. Generates a fresh access token via JWT assertion (RFC 7523).

# Get service account key
kubectl get secret -n zitadel iam-admin-jwt -o jsonpath='{.data.private-key\.json}' | base64 -d > /tmp/sa-jwt.json

# Exchange JWT assertion for access token
SA_TOKEN=$(python3 <<'PYEOF'
import json, time, jwt

with open('/tmp/sa-jwt.json') as f:
    sa = json.load(f)

now = int(time.time())
assertion = jwt.encode({
    'iss': sa['userId'],
    'sub': sa['userId'],
    'aud': 'https://auth.example.com/oauth/v2/token',
    'iat': now,
    'exp': now + 3600
}, sa['key'], algorithm='RS256')
print(assertion)
PYEOF
)

TOKEN=$(curl -s -X POST "https://auth.example.com/oauth/v2/token" \
  -d "grant_type=client_credentials" \
  -d "scope=urn:zitadel:iam:org:project:id:zitadel:aud" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=$SA_TOKEN" | jq -r '.access_token')

echo "$TOKEN"