# API keys and authentication

Create a read-only API key, monitor its usage, rotate it, or connect an AI assistant with OAuth.

Use an **API key for scripts and integrations**, or **OAuth for an MCP assistant**. Both belong to your existing Trawle account. There is no separate developer account.

## Create your first key

1. Open [API keys in your account](https://trawle.com/account#api-keys) and sign in.
2. Choose **Create API key**. Give it a name you will recognize, such as “n8n morning digest”.
3. Choose an expiry: 30 days, 90 days, or one year.
4. Copy the secret. It is shown **once**; Trawle stores a hash, not a recoverable copy.
5. Save it as `TRAWLE_API_KEY` in your server's environment or your automation tool's credential store.

Each key can read public jobs, companies and lookups. It cannot access your account, full job descriptions, or saved searches. Keep it out of browser bundles and source control.

## Make a request

```bash
curl "https://trawle.com/v1/stats" \
  -H "x-api-key: $TRAWLE_API_KEY"
```

```ts
const response = await fetch("https://trawle.com/v1/stats", {
  headers: { "x-api-key": process.env.TRAWLE_API_KEY! },
});
if (!response.ok) throw new Error(`Trawle returned ${response.status}`);
const stats = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://trawle.com/v1/stats",
    headers={"x-api-key": os.environ["TRAWLE_API_KEY"]},
    timeout=15,
)
response.raise_for_status()
stats = response.json()
```

## Limits and usage

Each API key allows **1,000 requests per daily window**. The account page shows recent usage, last use and expiry. Limits are enforced by Better Auth's database-backed key limiter across Lambda instances. Public traffic also has a per-IP burst limit of 120 requests per minute per instance.

Public data endpoints also accept anonymous requests with the per-IP limit. Supplying an invalid key returns `401`; it never silently falls back to anonymous access. Exhausted keys return `429` with `Retry-After`. See [errors](https://developers.trawle.com/guides/errors).

Data changes once a day. Cache results in your integration and use [`postedSince` and `nextSince`](https://developers.trawle.com/guides/daily-new-jobs) for scheduled searches. Credentialed HTTP responses are private and are not stored in the shared CDN cache.

## Rotate or revoke

Create a replacement key, update your integration, verify a request succeeds, then revoke the old key from your account. Revocation takes effect on the next request. If a key expires or is lost, create a new one; the original secret cannot be revealed again.

## Connect an AI app

MCP clients connect to `https://trawle.com/mcp` using **OAuth 2.1 with PKCE**. You sign in to Trawle and approve read-only `jobs:read` access. `offline_access` lets the client renew access without another sign-in.

Modern clients use Client ID Metadata Documents (CIMD). Dynamic registration is also available for released clients that still need it. Trawle publishes standard authorization-server and protected-resource discovery metadata, and validates tokens specifically for `/mcp`. API keys are for `/v1` requests; they are not MCP bearer tokens.

Manage authorized apps at [Account → Connected AI apps](https://trawle.com/account#apps). Disconnecting removes consent and refresh grants immediately. Already-issued access tokens expire within **five minutes**. Deleting your account also removes its keys and grants.

See [MCP setup](https://developers.trawle.com/mcp) for client configuration. Every integration should follow the [attribution and data policy](https://developers.trawle.com/guides/attribution).