OAuth via ZITADEL

ZITADEL is InBlack’s identity provider. Production tokens are issued under https://auth.inblack.app; staging uses https://auth.staging.inblack.app.

This page describes the contract InBlack services currently verify. It does not publish a self-service third-party OAuth client-registration flow because the platform source does not define one.

Current MCP status

The public MCP endpoint accepts a ZITADEL bearer access token. It does not yet expose the complete OAuth authorization-server runtime expected by remote MCP clients. MCP clients must therefore receive an access token through a supported InBlack sign-in or administrator flow and send it on every request.

Do not assume that an MCP client will open a browser, register itself, refresh a token, or show a tenant picker against the current endpoint.

Issuer and verification

The Worker validates access tokens using the issuer’s /oauth/v2/keys JWKS endpoint. Verification requires:

An allowed asymmetric signing algorithm (RS256, RS384, RS512, PS256, PS384, or PS512).
The configured issuer.
One of the configured ZITADEL project audiences.
A non-empty sub claim.
A valid token lifetime, with 30 seconds of clock tolerance in the Worker.

The concrete project audience is deployment configuration and is not published as a hostname or guessed client ID. Use a token issued for the InBlack application you are integrating with.

Claims used by MCP

The Worker derives this principal context from the verified JWT:

Claim	Use
`sub`	Stable principal subject; required
`email`, `name`, profile claims	Display identity when present
`scope`	Space-delimited or array scopes
`aud`	One or more token audiences
ZITADEL project role claims	Principal roles

The Worker does not select the MCP tenant from a JWT tenant_id claim. Send X-Tenant-ID after organization selection. The Worker then fetches tenant policy and verifies visibility for that principal.

Request example

POST /mcp HTTP/1.1
Host: ai-coo.inblack.app
Authorization: Bearer <zitadel-access-token>
X-Tenant-ID: <tenant-id>
Content-Type: application/json

Without X-Tenant-ID, the public MCP surface exposes only bootstrap organization-selection behavior. Internal MCP always requires the tenant header.

HTTP APIs

Go APIs use the shared auth package to verify ZITADEL tokens, resolve claims, and load tenant membership. Their exact tenant-resolution and scope requirements are endpoint-specific. Follow each API guide instead of assuming the MCP header contract applies unchanged to every service.

Client registration and refresh

Authorization endpoints, redirect URIs, client IDs, allowed third-party scopes, refresh-token lifetimes, and revocation UI are deployment and product contracts that are not established by the checked-in public integration surface. Do not hard-code inferred values.

For a new third-party OAuth integration, obtain an approved client registration and exact environment settings from InBlack. For current MCP client setup, use Bearer tokens and the explicit-header quickstarts.