How does a client or AI agent authenticate against the Maditon API?
With an OIDC bearer token issued by Zitadel, sent as an Authorization: Bearer header. The API validates it against Zitadel's JWKS endpoint on every request. Access tokens are short-lived — 15 minutes — with refresh tokens handling renewal, and every call is scoped to the organisation in the token.
Authentication is OIDC. Maditon does not issue its own API keys and never handles passwords itself.
The flow. Obtain a token from Zitadel through a standard OAuth 2.0 flow
with PKCE, then send it as Authorization: Bearer <token> on each request.
The backend validates the signature against Zitadel’s JWKS endpoint and reads
the organisation and user identity from the claims.
Lifetimes. Access tokens are short — 15 minutes — so a long-running agent must handle refresh rather than caching a token indefinitely. A 401 on a previously working call usually means expiry, not revocation.
Scope. Every authenticated endpoint is scoped to the organisation in the token. There is no cross-organisation read, including for support.
Rate limits. Authenticated callers are limited to roughly 10 requests per
second, and the unauthenticated public forms to 5 per hour per IP. Exceeding a
limit returns 429 with a Retry-After header — respect it rather than
retrying immediately.
Zitadel is Swiss-hosted, which keeps identity inside European jurisdiction along with the rest of the stack.
Read next
A free Solo account runs a real classification on one of your own systems — no card, no sales call.
Run a free classification