Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

Update service JWT provider

PUT/v1/organizations/{organizationId}/services/{serviceId}/jwtProviders/{jwtProviderName}
API playground

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

Replaces the configuration of a JWT authentication provider. The JWKS URL is fetched and validated before the change is saved.

Errors:

  • 400: invalid provider name or field values, or the JWKS URL is unreachable or does not return a key set with a supported signing key.
  • 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, is not visible to the caller, or has no provider with this name.

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
  • jwtProviderNamestringrequired

    Name of the JWT authentication provider.

Request bodyJSON

  • 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). The request replaces the whole provider configuration, so omitting this field removes an existing 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"