JWT Authentication

JWT (JSON Web Token) authentication enables programmatic access to Opik using externally issued tokens. This is ideal for service-to-service authentication, custom auth flows, and integration with existing JWT-based systems.

When to use JWT authentication

JWT authentication is best suited for:

• Backend services that need to access Opik's API
• CI/CD pipelines running automated experiments
• Custom applications with existing JWT infrastructure
• Service-to-service communication without user interaction

For human users logging in interactively, consider SAML or OIDC SSO instead.

Prerequisites

Before configuring JWT authentication, you need:

• Organization admin access to Opik
• Enterprise plan enabled for your organization
• JWT infrastructure capable of issuing signed tokens
• JWKS endpoint (recommended) or public key for token verification

How JWT authentication works

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Service/   │      │    Opik      │      │    JWKS      │
│   Client     │      │    API       │      │   Endpoint   │
└──────┬───────┘      └──────┬───────┘      └──────┬───────┘
       │                     │                     │
       │  1. Request with    │                     │
       │     JWT in header   │                     │
       │────────────────────>│                     │
       │                     │  2. Fetch keys      │
       │                     │     (cached)        │
       │                     │────────────────────>│
       │                     │<────────────────────│
       │                     │                     │
       │                     │  3. Verify JWT      │
       │                     │     signature       │
       │                     │                     │
       │                     │  4. Validate claims │
       │                     │     (iss, aud, sub) │
       │                     │                     │
       │  5. API response    │                     │
       │<────────────────────│                     │

1. Client sends an API request with a JWT in the Authorization header.
2. Opik fetches public keys from your JWKS endpoint (cached for performance).
3. Opik verifies the JWT signature using the appropriate key.
4. Opik validates claims (issuer, audience, subject).
5. If valid, the request is processed as the mapped user.

Configuration options

JWT authentication can be configured with either:

Configuring JWT authentication

Step 1: Navigate to SSO settings

1. Go to Admin Dashboard > SSO Configuration.
2. Select JWT Authentication (may be under advanced options).

Step 2: Choose key verification method

Using JWKS URI

JWKS (JSON Web Key Set) is the recommended approach as it:

• Supports automatic key rotation
• Allows multiple keys for seamless rotation
• Follows industry best practices

Configuration:

Requirements:

• The endpoint must be publicly accessible (or accessible from Opik's servers).
• Must return valid JWKS JSON format.
• Must be unique across organizations (no two orgs can share a JWKS URI).
• Should support HTTPS.

Example JWKS response:

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-1",
      "use": "sig",
      "n": "0vx7agoebGcQ...",
      "e": "AQAB"
    }
  ]
}

Using static public key

Static public key configuration is simpler but requires manual key rotation:

Format:

The public key must be in PEM format:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----

Step 3: Configure subject mapping

Subject mapping determines how Opik identifies users from JWT claims:

Subject mapping types:

Custom claim name:

By default, Opik reads the sub (subject) claim. If your tokens use a different claim:

{
  "sub": "12345",
  "email": "[email protected]",
  "preferred_username": "jsmith"
}

Set Subject Claim Name to email or preferred_username to use those claims instead.

Step 4: Configure optional restrictions

Allowed issuers

Restrict which token issuers are accepted:

Example:

https://auth.company.com
https://auth.partner.com

If configured, tokens with issuers not in this list will be rejected.

Allowed audiences

Restrict which audiences are accepted:

Example:

opik-api
https://api.opik.com

If configured, tokens without a matching audience claim will be rejected.

JWT token requirements

Required claims

Your JWT tokens must include:

Recommended claims

Required header

When using JWKS with multiple keys:

Using JWT authentication

API requests

Include the JWT in the Authorization header:

curl -X GET "https://api.opik.com/v1/projects" \
  -H "Authorization: Bearer <your-jwt-token>"

SDK configuration

Configure the Opik SDK to use JWT authentication:

import opik

# Configure with JWT token
client = opik.Opik(
    api_key="<your-jwt-token>",
    workspace="your-workspace"
)

import { Opik } from 'opik';

const client = new Opik({
  apiKey: '<your-jwt-token>',
  workspace: 'your-workspace'
});

Key caching and performance

JWKS caching

Opik caches JWKS responses to improve performance:

• Cache duration: Keys are cached and periodically refreshed.
• Automatic refresh: Keys are fetched on cache expiry or when a new kid is encountered.
• Fallback: If JWKS endpoint is temporarily unavailable, cached keys are used.

Configuration options (on-premises)

On-premises deployments can configure caching behavior:

Troubleshooting

Common issues

Debugging JWT tokens

Decode and inspect your JWT token (do not use for production tokens containing secrets):

# Decode JWT header and payload (without verification)
echo "<your-jwt>" | cut -d'.' -f1 | base64 -d 2>/dev/null | jq .
echo "<your-jwt>" | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .

Or use jwt.io to inspect token contents.

Verifying JWKS endpoint

Test that your JWKS endpoint is accessible and returns valid JSON:

curl -s "https://auth.company.com/.well-known/jwks.json" | jq .

Verify that:

• The endpoint returns HTTP 200.
• Response is valid JSON with a keys array.
• Keys include kid, kty, and algorithm-specific fields.

Token generation checklist

Before integrating, verify your tokens:

1. Signature: Token is signed with a key in your JWKS.
2. Header: Includes kid matching a key in JWKS (if multiple keys).
3. Subject: Contains user email or username in the configured claim.
4. Expiration: exp claim is in the future.
5. Issuer: Matches allowed issuers (if configured).
6. Audience: Matches allowed audiences (if configured).

Security best practices

Token lifecycle

• Short expiration: Use short-lived tokens (e.g., 1 hour).
• Refresh tokens: Implement token refresh for long-running processes.
• Revocation: Have a process to rotate keys if compromised.

Key management

• Key rotation: Rotate keys periodically (e.g., every 90 days).
• Multiple keys: Maintain multiple keys in JWKS during rotation.
• Secure storage: Protect private keys used for signing.

Access restrictions

• Limit issuers: Configure allowed issuers to prevent token from unauthorized sources.
• Limit audiences: Configure allowed audiences to ensure tokens are intended for Opik.
• Monitor usage: Review authentication logs for anomalies.

Next steps

• Configure SAML for interactive user authentication.
• Configure OIDC for OAuth-based authentication.
• Create service accounts for an alternative programmatic access method.