Bearer tokens (ZITADEL access tokens)

The public MCP surface authenticates ZITADEL JWT access tokens sent as HTTP bearer credentials. A token identifies a principal; it does not replace tenant membership, tenant policy, or per-tool visibility checks.

When to use one

Use a bearer access token for a user or machine principal that has been issued a token for the configured InBlack ZITADEL project. For public MCP, API keys and Worker service tokens are not alternatives:

Credential	Public MCP	Internal MCP	Product APIs
ZITADEL bearer token	Yes	Only with internal scope or role	Endpoint-specific
Worker service token	No	Yes	Internal service-specific
Tenant API key	No	No	Supported API endpoints only
Storefront SDK key	No	No	Storefront endpoints only

Send the token

Authorization: Bearer <zitadel-access-token>

For tenant-scoped MCP requests, also send:

X-Tenant-ID: <tenant-id>

Send both headers on every request because the public MCP transport is request-scoped and stateless.

Validation

The Worker verifies:

A bearer token is present.
The JWT signature resolves through the configured issuer’s JWKS.
The signing algorithm is allowed.
The issuer matches the environment.
The audience matches a configured ZITADEL project audience.
The JWT is within its valid lifetime.
sub is present.

Production issuer: https://auth.inblack.app

Staging issuer: https://auth.staging.inblack.app

The audience value is a deployment project ID, not api.inblack.app or another inferred hostname.

Principal context

After verification, the Worker extracts subject, optional profile fields, scopes, audiences, and ZITADEL project roles. It classifies tokens with openid or profile claims as human principals and other tokens as machine principals.

Tenant selection is separate. X-Tenant-ID chooses the tenant context, then the Worker obtains tenant policy using the bearer token and filters tools. A valid token for a principal without access to that tenant does not gain access by sending its ID.

Expiration and storage

Use the token’s exp claim as the authority for expiration; the guide does not assume a universal one-hour lifetime. When a token expires, obtain a new token through the supported issuing client or administrator flow.

Treat access tokens as secrets:

Keep them out of source control, logs, URLs, screenshots, and shared configuration.
Prefer an OS keychain or the client’s secret/environment facility.
Replace tokens in transitional MCP client configuration when they expire.
Do not send production tokens to staging or staging tokens to production.

Errors

Error	Meaning
`missing_bearer_token`	No usable `Authorization: Bearer` header
`invalid_bearer_token`	Signature, issuer, audience, lifetime, algorithm, or claim validation failed
`insufficient_scope`	Internal MCP token lacks the internal scope or role
`tenant_policy_unavailable`	Tenant policy could not be verified for the principal and tenant