Authentication
Reference for Judgment API keys, organization identity, and the clients that support OAuth.
Judgment SDK, JQL, OTLP, and MCP clients all authenticate a user, then scope work to an organization. The exact transport differs by client.
Credentials and identity
| Value | Purpose | Where to find it |
|---|---|---|
JUDGMENT_API_KEY |
Authenticates the Judgment user. | Open Settings → Account & API Key and create or copy an API key. |
JUDGMENT_ORG_ID |
Selects an organization where that user is a member. | Copy the organization ID from the organization menu, URL, or Command Menu shortcut. |
Store both as secrets in the server or worker environment. Do not publish them in source, logs, browser bundles, or public examples.
Judgeval SDK and JQL
The Python and TypeScript Judgeval clients read JUDGMENT_API_KEY and
JUDGMENT_ORG_ID from the environment. The API key identifies the user, the
organization ID selects one of that user’s organizations, and the project name
passed to the client selects the project within that organization.
export JUDGMENT_API_KEY="<your-api-key>"
export JUDGMENT_ORG_ID="<your-organization-id>"from judgeval import Judgeval
client = Judgeval(project_name="my-project")export JUDGMENT_API_KEY="<your-api-key>"
export JUDGMENT_ORG_ID="<your-organization-id>"import { Judgeval } from "judgeval";
const client = await Judgeval.create({ projectName: "my-project" });JQL uses this same client scope. Credentials, organization IDs, project IDs, trace IDs, and session IDs do not belong inside the JQL query expression.
Direct OTLP/HTTP export
Send all three headers to the trace-ingestion endpoint:
| Header | Value |
|---|---|
Authorization |
Bearer <JUDGMENT_API_KEY> |
X-Organization-Id |
<JUDGMENT_ORG_ID> |
X-Project-Id |
<JUDGMENT_PROJECT_ID> |
The API key must belong to a user who is a member of the specified
organization. X-Project-Id selects the project directly rather than by name.
See Direct OTEL for
the endpoint and exporter examples.
MCP clients
The Judgment MCP server supports either:
- OAuth 2.1 with PKCE in MCP clients that can complete the browser-based authorization flow.
- A Judgment API key sent as an
Authorization: Bearer <key>header.
OAuth support is specific to compatible MCP clients. It does not replace the API-key and organization configuration required by Judgeval SDK, JQL, or direct OTLP examples.
With an unbound API-key connection, call list_organizations, then supply
organization_id to organization- and project-scoped tools and project_id
to project-scoped tools. OAuth binds the connection to an organization and
optionally a project. Bound scope fields are removed from the advertised tool
schemas and injected server-side. See Connect the Judgment MCP
server for client configuration.
Failure reference
| Failure | Meaning |
|---|---|
Missing or malformed Authorization |
The Bearer API key was not sent in the required format. |
| Invalid API key | The supplied key does not identify a current Judgment user key. |
Missing X-Organization-Id |
An API request that requires organization scope did not receive it. |
| Organization membership denied | The authenticated user is not a member of the selected organization. |
Missing X-Project-Id on OTLP export |
Direct trace ingestion cannot select a project. |