Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Create service JWT provider

POST/v1/organizations/{organizationId}/services/{serviceId}/jwtProviders
API playground

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

Adds a JWT authentication provider to the service. Users can then connect to the service with a JWT issued by the provider; they are signed in as the default user and receive the roles listed in the roles claim. The JWKS URL is fetched and validated before the provider is saved. If the service already has a provider with this name and the same configuration, the request succeeds without changing it, so it is safe to retry.

Errors:

  • 400: invalid field values, the JWKS URL is unreachable or does not return a key set with a supported signing key, or the service already has 5 providers.
  • 401: missing, invalid, or disabled API key.
  • 403: caller lacks control-plane:service:manage on the service, or the organization does not have the JWT authentication providers feature (Enterprise tier).
  • 404: service does not exist or is not visible to the caller.
  • 409: the service already has a provider with this name and a different configuration.

Permission

The API key must have the control-plane:service:manage permission.

Authorizations

Path parameters

  • organizationIdstringrequired

    ID of the organization that owns the service.

    format: uuid
  • serviceIdstringrequired

    ID of the service.

    format: uuid

Request bodyJSON

  • namestringrequired

    Name of the JWT provider, unique within the service. Lowercase letters, digits and hyphens, at most 59 characters. Cannot be one of, or start with one of followed by a hyphen: cloud, clickhouse, ch, internal, system, default.

    maxLength: 59, pattern: ^[a-z0-9-]{1,59}$
    Example: "my-oidc-provider"
  • issuerstringrequired

    Expected iss claim of the tokens. Printable ASCII without whitespace, at most 256 characters.

    maxLength: 256
    Example: "https://auth.example.com"
  • audiencestringrequired

    Expected aud claim of the tokens. Printable ASCII without whitespace, at most 256 characters.

    maxLength: 256
    Example: "my-clickhouse-service"
  • jwksUrlstringrequired

    Public https:// URL of the JSON Web Key Set used to verify token signatures, at most 256 characters. The key set must contain at least one supported signing key: RS256 (RSA), or on ClickHouse 26.8 and later also ES256, ES384 or ES512 (EC); it is fetched and validated when the provider is created or updated.

    maxLength: 256
    Example: "https://auth.example.com/.well-known/jwks.json"
  • rolesClaimoptionalstring

    Name of the token claim that lists the ClickHouse roles to grant the user. Printable ASCII without whitespace, at most 256 characters, and not a registered JWT claim (iss, sub, aud, exp, nbf, iat, jti). Omit to configure no roles claim.

    Example: "clickhouse:roles"

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    5 properties
    • namestringrequired

      Name of the JWT provider, unique within the service. Lowercase letters, digits and hyphens, at most 59 characters. Cannot be one of, or start with one of followed by a hyphen: cloud, clickhouse, ch, internal, system, default.

      maxLength: 59, pattern: ^[a-z0-9-]{1,59}$
      Example: "my-oidc-provider"
    • issuerstringrequired

      Expected iss claim of the tokens. Printable ASCII without whitespace, at most 256 characters.

      maxLength: 256
      Example: "https://auth.example.com"
    • audiencestringrequired

      Expected aud claim of the tokens. Printable ASCII without whitespace, at most 256 characters.

      maxLength: 256
      Example: "my-clickhouse-service"
    • jwksUrlstringrequired

      Public https:// URL of the JSON Web Key Set used to verify token signatures, at most 256 characters. The key set must contain at least one supported signing key: RS256 (RSA), or on ClickHouse 26.8 and later also ES256, ES384 or ES512 (EC); it is fetched and validated when the provider is created or updated.

      maxLength: 256
      Example: "https://auth.example.com/.well-known/jwks.json"
    • rolesClaimoptionalstring

      Name of the token claim that lists the ClickHouse roles to grant the user. Printable ASCII without whitespace, at most 256 characters, and not a registered JWT claim (iss, sub, aud, exp, nbf, iat, jti). Absent when no roles claim is configured.

      Example: "clickhouse:roles"