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

# Authentication

> Two ways to authenticate: OAuth for Claude.ai and the Anthropic directory, personal URL for everything else.

UniversalBench supports two authentication methods. Which one you use depends on how you are connecting.

## OAuth (Claude.ai and the Anthropic Connectors Directory)

When you connect UniversalBench through the Anthropic Connectors Directory or Claude.ai, authentication is handled by the standard OAuth flow. You click Connect, sign in or create an account, and Claude.ai receives a token it uses on your behalf. There is nothing to configure manually.

The OAuth endpoint is:

```
https://universalbench-mcp.penantiaglobal.workers.dev/mcp
```

Claude.ai discovers this automatically via the directory listing. You never need to copy or paste this URL yourself.

## Personal URL (Claude Desktop, Cursor, Claude Code, custom agents)

For any MCP client outside of Claude.ai, UniversalBench bakes your identity into a personal URL. Copy it from your dashboard at [universalbench.dev](https://universalbench.dev) after signup:

```
https://universalbench-mcp.penantiaglobal.workers.dev/u/ubk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

The `ubk_` prefix identifies a UniversalBench key. The 64-character hex string is the secret. Paste the full URL into your client config with no extra headers needed.

<Note>
  **Why URL-embedded auth instead of a header?**

  Most MCP services use a shared endpoint plus an `X-API-Key` header. Every client handles custom headers differently and some break silently. Embedding the key in the URL path means one paste works everywhere, including clients with no header support.
</Note>

### Treat your URL like a password

Anyone with your URL can make calls billed to your account. To minimize risk:

* Do not commit it to public repositories
* Do not paste it into screenshots or shared logs
* Rotate it immediately if you suspect exposure by clicking "Rotate key" in your dashboard

### Alternative header methods

If you cannot use the URL form for some reason, the API also accepts the key via:

| Method               | Example                                                      |
| :------------------- | :----------------------------------------------------------- |
| Authorization header | `Authorization: Bearer ubk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
| Custom header        | `X-Api-Key: ubk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`            |
| Query parameter      | `?key=ubk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`                  |

All methods work against the base URL. The URL-embedded form is recommended.

## Check your quota and balance

```bash theme={null}
curl -H "Authorization: Bearer ubk_your_key" \
  https://universalbench-mcp.penantiaglobal.workers.dev/billing/status
```

Response:

```json theme={null}
{
  "tier": "free",
  "free_remaining_this_month": 993,
  "free_monthly_limit": 1000,
  "wallet_balance_usd": "0.00",
  "paid_calls_available": 0,
  "paid_call_cost_usd": "0.008",
  "min_topup_usd": "5.00",
  "max_topup_usd": "500.00"
}
```

## Sign in via magic link

To get a fresh dashboard session without a password:

```bash theme={null}
curl -X POST https://universalbench-mcp.penantiaglobal.workers.dev/magic-link \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
```

A link valid for 15 minutes is sent to your email.