> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create service JWT provider > **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 valid RS256 key set, 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. Beta **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 valid RS256 key set, 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. ## OpenAPI ````yaml _specs/cloud-openapi.json POST /v1/organizations/{organizationId}/services/{serviceId}/jwtProviders openapi: 3.1.1 info: title: OpenAPI spec for ClickHouse Cloud version: '1.0' contact: name: ClickHouse Support url: >- https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1372680 email: support@clickhouse.com servers: - url: https://api.clickhouse.cloud security: - basicAuth: [] tags: - name: Organization - name: Notifications - name: User management - name: Billing - name: Role Management - name: Service - name: Backup - name: Snapshot - name: API keys - name: Prometheus - name: ClickPipes - name: ClickStack - name: Postgres - name: UDF - name: Query API endpoints - name: Saved queries paths: /v1/organizations/{organizationId}/services/{serviceId}/jwtProviders: post: tags: - Service summary: Create service JWT provider description: >- **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 valid RS256 key set, 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. operationId: jwtProviderCreate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/JwtProviderPostRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/JwtProvider' '400': description: >- The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: >- An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid components: schemas: JwtProviderPostRequest: properties: name: description: >- 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`. type: string example: my-oidc-provider maxLength: 59 pattern: ^[a-z0-9-]{1,59}$ issuer: description: >- Expected `iss` claim of the tokens. Printable ASCII without whitespace, at most 256 characters. type: string example: https://auth.example.com maxLength: 256 audience: description: >- Expected `aud` claim of the tokens. Printable ASCII without whitespace, at most 256 characters. type: string example: my-clickhouse-service maxLength: 256 jwksUrl: description: >- 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 RS256 (RSA) key; it is fetched and validated when the provider is created or updated. type: string example: https://auth.example.com/.well-known/jwks.json maxLength: 256 rolesClaim: description: >- 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. type: string example: clickhouse:roles required: - name - issuer - audience - jwksUrl JwtProvider: properties: name: description: >- 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`. type: string example: my-oidc-provider maxLength: 59 pattern: ^[a-z0-9-]{1,59}$ issuer: description: >- Expected `iss` claim of the tokens. Printable ASCII without whitespace, at most 256 characters. type: string example: https://auth.example.com maxLength: 256 audience: description: >- Expected `aud` claim of the tokens. Printable ASCII without whitespace, at most 256 characters. type: string example: my-clickhouse-service maxLength: 256 jwksUrl: description: >- 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 RS256 (RSA) key; it is fetched and validated when the provider is created or updated. type: string example: https://auth.example.com/.well-known/jwks.json maxLength: 256 rolesClaim: description: >- 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. type: string example: clickhouse:roles required: - name - issuer - audience - jwksUrl securitySchemes: basicAuth: type: http scheme: basic description: >- Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi x-permission-scopes: >- The scope list of a `security` requirement holds ClickHouse Cloud API key permission ids (for example `control-plane:organization:view`), not OAuth scopes. OpenAPI has no field for API key permissions, so this is the closest available place. A key must hold every permission listed on an operation to call it; an operation with no scopes needs none beyond a valid key. Every operation declares at most one requirement object, always for this scheme, so the list is only ever conjunctive — alternative sets of permissions are never expressed. ````