API keys and authentication

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

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.

Data changes once a day. Cache results in your integration and use postedSince and nextSince 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. 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 for client configuration. Every integration should follow the attribution and data policy.