--- title: "JSON Web Token authentication in Connector builder | Supermetrics" slug: "jwt-authentication" description: "Learn how to configure JSON Web Token (JWT) authentication for APIs, including Google BigQuery, with secure signing and claims management." updated: 2026-07-23T12:10:07Z published: 2026-07-23T12:10:07Z canonical: "docs.supermetrics.com/jwt-authentication" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # JSON Web Token authentication JSON Web Token (JWT) authentication is used by APIs that require a signed token to prove the caller's identity. Instead of exchanging a username and password, the connector builds a JWT, signs it with a private key, and uses it to authenticate. This is common for service-account style access — for example, Google BigQuery. To configure JWT authentication, add an `authentication` component with `type: "jwt"` and a `jwt` object. You define the signing algorithm, the signing key, and the claims to include in the token. Supermetrics builds, signs, and manages the token for you. ## Prerequisites for configuring JWT authentication To configure JWT authentication, you need: - The **signing algorithm** the API expects — `RS256` (RSA with SHA-256) or `ES256` (ECDSA with SHA-256). - The **signing key** — a PEM-encoded private key. This is sensitive and must be encrypted or stored as a [secret](https://docs.supermetrics.com/docs/secrets). - The **claims** the API requires in the token payload, such as the issuer (`iss`), subject (`sub`), and audience (`aud`). ## Template JWT authentication configuration Below you can find a template configuration that you can fill in with your own information for an easier start: ``` { "authentication": { "type": "jwt", "description": "[Description shown to users during the authentication flow]", "jwt": { "signingAlgorithm": "RS256", "secret": { "source": "secret", "value": "[secret id for the private key]" }, "keyId": { "source": "secret", "value": "[secret id for the key ID]" }, "tokenLifetime": 3600, "includeIssuedAtClaim": true, "includeExpirationClaim": true, "claims": [ { "name": "iss", "value": { "source": "userInput", "value": "[input id]" } }, { "name": "aud", "value": { "source": "static", "value": "[audience]" } } ] } }, "secrets": { "items": [ { "id": "[secret id for the private key]", "classification": "secret", "source": "userInput", "value": "[id of the user input field that holds the private key]" }, { "id": "[secret id for the key ID]", "classification": "secret", "source": "userInput", "value": "[id of the user input field that holds the key ID]" } ] } } ``` ## Configuration fields ### jwt | Field | Type | Required | Description | | --- | --- | --- | --- | | `signingAlgorithm` | string | Yes | The algorithm used to sign the token. Supported values: `RS256`, `ES256`. | | `secret` | value source | Yes | Resolves to the signing key. For `RS256`, the PEM-encoded RSA private key; for `ES256`, the PEM-encoded EC private key. | | `keyId` | value source | No | Resolves to the key ID (`kid` header claim) used for signing. | | `passphrase` | value source | No | Resolves to the passphrase used to decrypt an encrypted private key. | | `tokenLifetime` | integer | No | How long the token is valid, in seconds. Default is `3600` (1 hour). | | `claims` | array | No | The claims to include in the token payload (see below). | | `includeIssuedAtClaim` | boolean | No | Whether to include the `iat` (issued at) claim. | | `includeExpirationClaim` | boolean | No | Whether to include the `exp` (expiration) claim. The expiration is calculated from `tokenLifetime`. | | `computePublicKeyFingerprint` | boolean | No | When `true`, the SHA-256 fingerprint of the public key is computed from the private key and made available as `{{jwt.public_key_fingerprint}}` for use in claims. | The `secret`, `keyId`, and `passphrase` fields are value sources. They can be resolved from `encrypted` (an encrypted value in the configuration), `userInput` (a value from a user input field), `jsonPath` (a value from a prior JSON response), or `secret` (a [secret](https://docs.supermetrics.com/docs/secrets) referenced by ID). ### claims Each entry in the `claims` array defines a single claim: | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | Yes | The name of the claim (e.g., `iss`, `sub`, `aud`). | | `value` | value source | Yes | The value of the claim. Use a single value source for a scalar claim, or an array of value sources for an array claim. | | `separator` | string | No | When `value` is an array of value sources, the resolved values are joined into a single string using this separator. | Claim values support these sources: `cookie`, `encrypted`, `header`, `jsonPath`, `userInput`, `static`, `responseStatus`, `responseReason`, `responseBody`, `networkError`, and `secret` (use `secret` for sensitive claim values). ## Configuring JWT authentication We'll walk through configuring JWT authentication using Google BigQuery as an example. BigQuery uses a service account: the connector signs a JWT with the service account's private key and includes the service account details as claims. In this example: - The token is signed with `RS256` using the private key and key ID provided by the user, which we register as [secrets](https://docs.supermetrics.com/docs/secrets). - The `iss` (issuer) and `sub` (subject) claims are set to the service account's email. - The `aud` (audience) claim is the BigQuery API. ### User inputs JWT authentication has no interactive authorization screen, so we collect the service account details the user provides through the `userInputs` array. Use the `password` type for sensitive values such as the private key and key ID so they're masked in the user interface: ``` "userInputs": [ { "id": "private_key", "label": "Private key", "type": "password" }, { "id": "key_id", "label": "Key ID", "type": "password" }, { "id": "client_email", "label": "Client email", "type": "text" } ] ``` ### Registering the credentials as secrets The private key and key ID come from the user, so instead of referencing the inputs directly we register them as [secrets](https://docs.supermetrics.com/docs/secrets). This keeps the values classified and access-restricted. Define each secret at the connector root: set `source` to `userInput` and `value` to the `id` of the user input field that collects it, with a `classification` of `secret`: ``` { "secrets": { "items": [ { "id": "jwt_private_key", "classification": "secret", "source": "userInput", "value": "private_key" }, { "id": "jwt_key_id", "classification": "secret", "source": "userInput", "value": "key_id" } ] } } ``` ### JWT configuration In the `jwt` object, reference each secret with `source: "secret"` and `value` set to the secret's `id`. The same approach applies to any other sensitive field, such as `passphrase`: ``` { "authentication": { "type": "jwt", "description": "Enter your Google service account details", "jwt": { "signingAlgorithm": "RS256", "secret": { "source": "secret", "value": "jwt_private_key" }, "keyId": { "source": "secret", "value": "jwt_key_id" }, "tokenLifetime": 3600, "includeIssuedAtClaim": true, "includeExpirationClaim": true, "claims": [ { "name": "iss", "value": { "source": "userInput", "value": "client_email" } }, { "name": "sub", "value": { "source": "userInput", "value": "client_email" } }, { "name": "aud", "value": { "source": "static", "value": "https://bigquery.googleapis.com/" } } ] } } } ``` > **Note** > > > If the private key is a fixed value shared across all users rather than entered per user, encrypt it with the secret encryption tool in the connector builder. The tool stores the value securely and registers the corresponding `secrets` entry for you automatically — you then reference it from the `jwt` object the same way, with `source: "secret"`. ### Full configuration Putting the user inputs, the `jwt` object, and the secrets together, the complete configuration looks like this: ``` { "authentication": { "type": "jwt", "description": "Enter your Google service account details", "userInputs": [ { "id": "private_key", "label": "Private key", "type": "password" }, { "id": "key_id", "label": "Key ID", "type": "password" }, { "id": "client_email", "label": "Client email", "type": "text" } ], "jwt": { "signingAlgorithm": "RS256", "secret": { "source": "secret", "value": "jwt_private_key" }, "keyId": { "source": "secret", "value": "jwt_key_id" }, "tokenLifetime": 3600, "includeIssuedAtClaim": true, "includeExpirationClaim": true, "claims": [ { "name": "iss", "value": { "source": "userInput", "value": "client_email" } }, { "name": "sub", "value": { "source": "userInput", "value": "client_email" } }, { "name": "aud", "value": { "source": "static", "value": "https://bigquery.googleapis.com/" } } ] } }, "secrets": { "items": [ { "id": "jwt_private_key", "classification": "secret", "source": "userInput", "value": "private_key" }, { "id": "jwt_key_id", "classification": "secret", "source": "userInput", "value": "key_id" } ] } } ``` ## Using the JWT in requests Once the JWT is built and signed, Supermetrics handles obtaining and managing the resulting access token. Use it in your requests as a Bearer token with the `{{user.access_token}}` placeholder: ``` "request": { "method": "POST", "url": "https://bigquery.googleapis.com/...", "headers": [ { "name": "Authorization", "value": "Bearer {{user.access_token}}" } ] } ```