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.
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 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.
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. 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}}"
    }
  ]
}

Documentation Index