Skip to main content
Send a credential in the Authorization header of each request to the Judt REST API (https://api.judt.ai/api) and the Judt MCP server (https://api.judt.ai/mcp).

API keys (primary)

An API key is the primary credential for scripts, CI jobs, and agents. Each API key starts with judt_. Send the key as a bearer token:
  • Create a key in the dashboard: On the API keys page, click Create key. Set a name and an expiration time (1 day to 90 days, or No expiration). Copy the key. The dashboard shows the full key one time only. A key from the dashboard reaches all Apps in the organization.
  • Create an App token with the API: To give an agent access to only one App, use an organization-wide API key to call POST /api/tokens. This endpoint creates a token for one App that expires after 60 to 86400 seconds (up to 24 hours). See Give an agent access to a single App.
  • Check a credential: Call GET /api/me to see the person, the organization, the role, and whether the credential reaches one App or all Apps.
  • Revoke a key: On the API keys page, open the menu of the key and click Revoke. The key stops working immediately.

Agent OAuth

With OAuth, you approve an agent or MCP client in your browser. You do not copy a key. The access token acts as you in the organization that you select and uses the apps:read and apps:write scopes. An agent can start OAuth in two ways:
  • From the MCP server: Connect an MCP client that supports OAuth (such as Claude Code, Cursor, VS Code, claude.ai, or ChatGPT) to https://api.judt.ai/mcp without an Authorization header. The server returns 401 Unauthorized with the resource_metadata URL in the WWW-Authenticate header, and the client opens your browser so you can sign in and approve access. See Connect to MCP.
  • From auth.md: An agent can register itself with only the email address of its user. For the full procedure, see https://judt.ai/auth.md:
    1. Read the server metadata at https://judt.ai/.well-known/oauth-authorization-server.
    2. Register at POST https://judt.ai/api/auth/agent/identity with type: "service_auth" and the email address in login_hint.
    3. Give the verification link (https://judt.ai/device) and the user code to the user. Only the account with that email address can approve the code.
    4. Poll POST https://judt.ai/api/auth/oauth2/token until the user approves access. The response has an access token and an identity assertion.
    5. To get a new access token, send the identity assertion to the same endpoint.
An agent that already uses the OAuth device flow can register as an OAuth client instead. An agent that uses the Personal Agent Protocol starts at https://judt.ai/.well-known/poppy.json. auth.md describes both. To disconnect an agent, go to Connections and click Disconnect. An agent can also revoke its own refresh token at POST https://judt.ai/api/auth/oauth2/revoke.

Other details

  • Organization roles: Every API key and OAuth token acts as you in one organization and has your role (owner, admin, or member). An agent cannot do an action that your role does not allow.
  • Tokens that open a private App: To open a published App (https://<slug>.judt.dev) that uses password or private visibility without a browser sign-in, create a 5-minute visitor token with POST /api/apps/{id}/visitor-tokens. Send this token in the X-Judt-Access-Token header or the access_token URL parameter. See Previews and access.
For OAuth scopes, token lifetimes, DPoP key binding, role permissions, and error codes, see the API reference.