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

# Authentication

> How to authenticate with the Court Rules API

All API endpoints require a Bearer token in the `Authorization` header.

## Request format

```
Authorization: Bearer <api_key>
```

## Getting an API key

API keys are issued through the console dashboard at [console.courtrules.app](https://console.courtrules.app). Sign in with your organization account to view and manage your keys.

Keys follow the format `crm_<env>_<random>` (e.g. `crm_prod_...`).

## Example request

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET 'https://api.courtrules.app/api/v1/judges?district_id=edny' \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Error responses

### 401: Missing or malformed header

Returned when the `Authorization` header is missing or doesn't use the `Bearer` scheme.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Missing or invalid Authorization header. Expected: Bearer <api_key>"
}
```

### 403: Invalid key

Returned when the key is present and well-formed but not recognized.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Invalid API key"
}
```

## MCP authentication

The MCP server at `https://mcp.courtrules.app/mcp` requires a credential on every request. There are two ways to get one, and neither makes you sign in again later.

| Method | How it works | Use it for |
| - | - | - |
| Sign in | Your MCP client opens console.courtrules.app, you approve once, the client refreshes its token | Claude Code, Claude Desktop, claude.ai, Cursor, VS Code, Codex |
| API key | `Authorization: Bearer <api_key>` header; keys do not expire | Scripts, backends, CI, and clients without sign-in |

### Sign in

Add the server URL to your client and sign in when it asks. Per-client steps are in the [MCP: Court Rules quick start](/guides/mcp-court-rules#quick-start).

How it works: a request without a credential gets `401` with a `WWW-Authenticate` header that points to `https://mcp.courtrules.app/.well-known/oauth-protected-resource`. Clients that support MCP sign-in (OAuth 2.1) read that, register themselves, and open the consent page. The access token they receive lasts one hour, and the client trades its refresh token for a new one in the background, so you are not asked again.

### API key

Your API key is on the dashboard at [console.courtrules.app](https://console.courtrules.app). It is the same key the REST API takes.

Claude Code:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude mcp add --transport http court-rules https://mcp.courtrules.app/mcp \
  --header "Authorization: Bearer $COURT_RULES_API_KEY"
```

Cursor, Windsurf, and other clients with a JSON config:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "mcpServers": {
    "court-rules": {
      "url": "https://mcp.courtrules.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Your own application, with the MCP TypeScript SDK:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const transport = new StreamableHTTPClientTransport(new URL("https://mcp.courtrules.app/mcp"), {
  requestInit: {
    headers: { Authorization: `Bearer ${process.env.COURT_RULES_API_KEY}` },
  },
});
```

### Errors

Every rejected request returns `401` with a `WWW-Authenticate` header.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": "invalid_token", "error_description": "Token expired" }
```

| `error` | `error_description` | Cause |
| - | - | - |
| `unauthorized` | `Sign in through your MCP client, or send an API key as Authorization: Bearer <api_key>` | No credential sent |
| `invalid_token` | `Token expired` | An access token past its one-hour lifetime that the client did not refresh |
| `invalid_token` | `Not a valid API key or OAuth access token` | A mistyped key, a revoked key, or a token not issued for this server |

### Common mistakes

* **Copying an access token into a static header.** Nothing refreshes it, so it stops working after an hour. Static headers should hold the API key.
* **Setting a header and expecting sign-in.** Claude Code skips sign-in for any server with an `Authorization` header configured. Use one method per server entry.

### Getting access

Sign in at [console.courtrules.app](https://console.courtrules.app) with Google or email. Contact [api@courtrules.app](mailto:api@courtrules.app) if your organization needs access provisioned.

## Security notes

* API keys are sensitive credentials. Do not commit them to version control or expose them in client-side code.
* Use environment variables to store keys in your application:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export COURT_RULES_API_KEY="crm_prod_..."
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET 'https://api.courtrules.app/api/v1/judges?district_id=edny' \
  -H "Authorization: Bearer $COURT_RULES_API_KEY"
```


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