Guides

JSON Web Token authentication

JSON Web Token (JWT) authentication adds a signed credential to a Conduit Nodes API key. You sign each token with an asymmetric key pair that you control, and Conduit verifies it with the public key registered to your organization.

JWT authentication is opt-in per API key. An API key without a bound public key continues to work as before. After you bind a public key, every request that uses that API key must include both:

  • The Nodes API key in the RPC endpoint URL.
  • A signed JWT in the Authorization: Bearer <JWT> header.

How authentication works

A JWT has three Base64URL-encoded parts: header.payload.signature. The header identifies the signing algorithm and public key, the payload contains time claims, and the signature lets Conduit detect changes and verify the signer.

  1. You generate an asymmetric public and private key pair.
  2. You register the public key with Conduit. Conduit derives a Key ID (kid) from it.
  3. You bind the public key to one or more Nodes API keys.
  4. You sign a JWT with the private key and include the Key ID in its header.
  5. Conduit selects the bound public key identified by kid, then verifies the algorithm, signature, and expiration.

Conduit supports these asymmetric signing algorithms:

  • RS256 with an RSA key.
  • ES256 with an elliptic curve P-256 key.
  • EdDSA with an Ed25519 key.

Conduit doesn’t support symmetric algorithms such as HS256. The algorithm selected for the registered public key must match its key type and the JWT signing algorithm.

Keep private keys in a secrets manager or another protected backend environment. Never upload a private key to Conduit, commit it to source control, or expose it in browser code. Conduit only needs the public key.

Get started

  1. Create a Nodes API key.
  2. In the Conduit app, open your organization settings and find JWT public keys.
  3. Add your public key in Privacy-Enhanced Mail (PEM) format and copy the generated Key ID.
  4. In Nodes, select your API key and open Authentication.
  5. Click Bind public key and select the registered public key.

Changes may take a moment to apply. Admin and Read-Write members can manage public keys and bindings. Read-Only members can view them.

Generate JWTs

Create an RS256 key pair with Node.js or Bash, then sign short-lived tokens with TypeScript or Go.

Make authenticated requests

Send both your Nodes API key and bearer token to a Conduit RPC endpoint.

To rotate credentials without interrupting requests, register a new public key and bind it before you stop signing with the old private key. Update your services to use the new Key ID, then unbind or delete the old public key.