> ## Documentation Index
> Fetch the complete documentation index at: https://docs.judt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate to the API and the MCP server

> Send an API key or an OAuth access token with each request to the Judt API and the Judt MCP server.

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

| Path | Who uses it | Access scope | How to start |
| - | - | - | - |
| **API key** *(primary)* | Scripts, CI jobs, and agents | All Apps in one organization, or one App | Create a `judt_...` key on the [API keys](https://judt.ai/api-keys) page, or create a short-lived App token with `POST /api/tokens`. |
| **Agent OAuth** | Coding agents and MCP clients | All Apps in one organization (`apps:read`, `apps:write`) | Connect an OAuth client to the MCP server, or follow [`https://judt.ai/auth.md`](https://judt.ai/auth.md). |

## 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:

```http theme={null}
Authorization: Bearer judt_...
```

* **Create a key in the dashboard**: On the [API keys](https://judt.ai/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](https://docs.judt.ai/manage/guides/agent-access.md).
* **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](https://judt.ai/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](https://docs.judt.ai/connect-to-mcp.md).
* **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`](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](https://judt.ai/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](https://docs.judt.ai/manage/concepts/previews.md).

For OAuth scopes, token lifetimes, DPoP key binding, role permissions, and error codes, see the [API reference](https://docs.judt.ai/api-reference/introduction.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.