JWT Authentication

​

Configuring JWT Authentication

​

JWKS Configuration

• JWKS URL: A URL from which the public keys will be dynamically fetched.
• JWKS JSON: A static JSON containing public keys.

​

Hard Requirements (Read First)

​

JWT Header (JOSE Header)

• alg: Must be RS256. Symmetric algorithms like HS256 are not accepted.
• typ: Must be JWT.
• kid: Required. The value in the JWT header must match a kid in your JWKS.

​

Key Requirements

• Key type: RSA
• Key size: 2048 bits or higher
• Your JWKS must expose only the public key parameters (e.g., kty, n, e, use, alg, kid). Do not include private key material.

​

JWT Requirements

​

Supported Algorithm

• JWTs must be signed using RS256 (RSA Signature with SHA-256).

​

Required Claims

• exp is mandatory. Tokens without exp or with expired exp are rejected.
• iat and/or nbf are recommended but optional.

​

User Identification

1. email_id
2. sub
3. uid

​

End-to-End Working Example (Generate → Configure JWKS → Sign → Call)

1. generate an RSA key pair,
2. create a JWKS containing the public key,
3. sign a JWT with the private key,
4. call Portkey with the JWT.

​

1) Prerequisites

# Node 18+ recommended
npm init -y
npm install jose

​

2) Generate RSA Keys, Create JWKS, and Sign a JWT (NodeJS)

import { generateKeyPair, exportJWK, SignJWT } from 'jose';
import { randomUUID } from 'node:crypto';
import fs from 'node:fs';

const { publicKey, privateKey } = await generateKeyPair('RS256');

// Create a public JWK for JWKS
const publicJwk = await exportJWK(publicKey);
publicJwk.kty = 'RSA';
publicJwk.use = 'sig';
publicJwk.alg = 'RS256';
publicJwk.kid = randomUUID();

const jwks = { keys: [publicJwk] };
fs.writeFileSync('jwks.json', JSON.stringify(jwks, null, 2));

const now = Math.floor(Date.now() / 1000);

// Sign a JWT with the private key
const jwt = await new SignJWT({
  portkey_oid: '<YOUR_ORG_ID>',
  portkey_workspace: '<YOUR_WORKSPACE_SLUG>',
  scope: ['completions.write', 'logs.view'],
  email_id: '[email protected]',
  sub: '<YOUR_USER_ID>'
})
  .setProtectedHeader({ alg: 'RS256', kid: publicJwk.kid, typ: 'JWT' })
  .setIssuedAt(now)
  .setExpirationTime(now + 60 * 60) // 1 hour
  .sign(privateKey);

fs.writeFileSync('token.jwt', jwt);

console.log('JWKS written to jwks.json');
console.log('JWT written to token.jwt');
console.log('kid:', publicJwk.kid);

node generate-and-sign-jwt.mjs

• jwks.json: A JWKS containing your public key (with a kid).
• token.jwt: A signed JWT ready to use with Portkey.

​

3) Add Your Public Key to Portkey (JWKS)

• Navigate to Admin Settings → Organisation → Authentication.
• Choose either:
  • JWKS URL: Host jwks.json at a reachable HTTPS URL and paste that URL.
  • JWKS JSON: Paste the entire contents of your generated jwks.json.
• Save changes.

​

4) Call Portkey Using the Signed JWT

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $(cat token.jwt)" \
  -H "x-portkey-provider: @<YOUR_PROVIDER_SLUG>" \
  -d '{
    "model": "your-model-id",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

​

Authentication Process

1. The client sends an HTTP request with the JWT in the x-portkey-api-key header:
   Copy

   Ask AI

   x-portkey-api-key: <JWT_TOKEN>
   

2. The server validates the JWT:
   • Verifies the signature using the JWKS.
   • Checks if the token is expired.
   • Ensures the required claims are present.
3. If valid, the request is authenticated, and user details are extracted for authorization and logging.
4. If invalid, the request is rejected with an HTTP 401 Unauthorized response.

​

Authorization & Scopes

​

Example JWT Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<YOUR_KID>"
}

• This matches the signing example (.setProtectedHeader({ alg: 'RS256', kid: publicJwk.kid, typ: 'JWT' })).
• Ensure kid exactly matches one key in your configured JWKS.

​

Example JWT Payload

{
  "portkey_oid": "3ed1b666-7e3d-416a-9260-da10e1610d1a",
  "portkey_workspace": "ws-shared-8622d1",
  "scope": ["completions.write", "logs.view"],
  "email_id": "[email protected]",
  "sub": "user-123",
  "exp": 1735689600
}

​

Making API Calls with JWT Authentication

npm install portkey-ai

import Portkey from 'portkey-ai';

const client = new Portkey({
  apiKey: '<JWT_TOKEN>', // Use JWT token instead of API key
  provider: '@<YOUR_PROVIDER_SLUG>'

});

async function main() {
  const response = await client.chat.completions.create({
    messages: [{ role: "user", content: "Hello, how are you today?" }],
    model: "your-model-id",
  });

  console.log(response.choices[0].message.content);
}

main();

​

Troubleshooting “Invalid API Key” Errors

• Wrong algorithm: Only RS256 is accepted; HS256 or others will fail.
• Missing or mismatched kid: Your JWT header must include a kid that matches a key in the JWKS.
• Incorrect header usage: Send the raw JWT in x-portkey-api-key without a Bearer prefix.
• Expired or missing exp: The exp claim is required and must be in the future. Allow for small clock skew.
• Private vs Public key mix-up: Your JWKS must contain only the public key parameters. The private key is used only for signing; never paste it into the JWKS JSON.
• Wrong org/workspace identifiers: portkey_oid (or organisation_id) and portkey_workspace (or workspace_slug) must correspond to valid identifiers in your Portkey tenant.
• Scopes missing for the API you call: E.g., chat completions needs completions.write.
• Unreachable JWKS URL: If using a URL, it must be publicly reachable by Portkey. For static JSON, ensure the pasted JSON is valid and includes keys: [...].

"jwtToken": "ey****bt",
"error": "Error Verifying JWT token: Signing Key Not Found",

​

Caching & Token Revocation

• JWTs are cached until they expire to reduce validation overhead.
• If you rotate keys:
  • Publish the new public key in JWKS with a new kid.
  • Start issuing tokens signed by the new private key (with the new kid).
  • Old tokens will remain valid until their exp is reached.