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.

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.

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

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   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.

JWT authentication can be configured with either:

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

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

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

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": "user@company.com",
  "preferred_username": "jsmith"
}

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

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.

Restrict which audiences are accepted:

Example:

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

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

Your JWT tokens must include:

When using JWKS with multiple keys:

Include the JWT in the Authorization header:

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

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'
});

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.

On-premises deployments can configure caching behavior:

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.

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.

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).

• 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 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.

• 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.

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