Catalogian has two kinds of credentials, and it is worth keeping them apart. Your credentials authenticate you (or your code, or your LLM) to Catalogian. Source credentials authenticate Catalogian to the origin your record watches. This page covers both, plus how each access route identifies itself.
| Credential | Prefix | Scope of access | Typical use |
|---|---|---|---|
| Account API key | cat_live_ | All records in your account | Backend services, CI/CD, admin scripts |
| Record-scoped key | cat_src_ | A single record only | Vendor integrations, agent configs, limited-access sharing |
| Ephemeral session token | cat_eph_ | One anonymous record for its 24-hour session | The homepage card flow, MCP for unkept records |
| OAuth (MCP) | n/a | Connector access to your account's records, issued per LLM client | Claude.ai connector authorization |
Scope is the rule on API keys: prefer the narrowest credential that works. A leaked record-scoped key exposes one record; a leaked account key exposes everything.
Pass the key in the Authorization header:
curl https://api.catalogian.com/v1/sources \ -H "Authorization: Bearer cat_live_your_key_here"
A record-scoped key (cat_src_) resolves its record automatically. You never pass a record ID, and the record's slug works directly:
# With a record-scoped key, both of these address the scoped record: GET /v1/sources GET /v1/sources/west-coast-earthquakes/delta/latest
GET /v1/sources with a record-scoped key returns only the scoped record, never the account.
| Scope | Available on | Permissions |
|---|---|---|
full | Account keys | Everything: create and edit records, manage keys, read, download |
read | Both | Read records, delta events, and row data, plus snapshot downloads |
download | Both | Export snapshot data as CSV/JSON files, nothing else |
The hierarchy is strict: full allows everything, read allows reads and downloads, and download allows downloads only. Write endpoints always require full. Ephemeral session tokens skip this table: the token is the session's credential, possession is control, and its powers end when the session does.
Account keys live in the dashboard under Settings → Developers; a record-scoped key lives on the record page's Connect tab (Record API Keys).
# Create an account key
curl -X POST https://api.catalogian.com/v1/apikeys \
-H "Authorization: Bearer $CATALOGIAN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CI Pipeline", "scope": "read"}'
# Create a record-scoped key
curl -X POST https://api.catalogian.com/v1/sources/:id/apikeys \
-H "Authorization: Bearer $CATALOGIAN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Vendor Integration", "scope": "read"}'Copy the key immediately. The full key value is shown once in the response. Keys are stored as SHA-256 hashes and cannot be retrieved later.
# Revoke an account key DELETE /v1/apikeys/:id # Revoke a record-scoped key DELETE /v1/sources/:id/apikeys/:keyId
Revoked keys stop working immediately and cannot be un-revoked. Create the replacement first, switch your integration over, then revoke.
The MCP server (https://api.catalogian.com/v1/mcp) accepts every credential type, and each record's card hands you a self-contained URL with the token already embedded (?token=...), so guided clients need no header config. The two transports are the Authorization header (preferred: it works with every credential type and stays out of logs and history) and the embedded-URL form (for clients that cannot set headers; it carries ephemeral session tokens). Claude.ai uses OAuth instead: connect once, authorize in Catalogian, and the connector carries MCP-scoped access. The full setup, per client, is in the MCP guide. Anonymous records get 50 tool calls per session; account records meter MCP calls by plan.
A URL record can watch a protected source. Catalogian fetches the URL itself, so the origin's credentials are configured on the record, not sent by your code. Supported methods:
| Method | authType value | Fields |
|---|---|---|
| None | none | Public URL, nothing sent |
| Basic auth | basic | authUsername, authPassword |
| Bearer token | bearer | authToken |
| API key in a header | api_key_header | authHeaderName, authHeaderValue |
| API key in the query | api_key_query | authQueryParam, authQueryValue |
Configure these when creating the record (the wizard has the same five choices), or update them later on the record's auth settings. Query-param auth appends ?api_key=value at fetch time (with & when the URL already has a query string).
Prefer token auth over network-level allowlists. Credentials travel with the record and keep working as infrastructure changes.
Source credentials are encrypted at rest with AES-256-GCM and are never returned by the API after creation: responses confirm that auth is configured without echoing the values.
API keys and webhooks unlock for the whole account once any one record is on a paid tier (watch or max). MCP is on every rung: anonymous sessions get 50 tool calls per session, and account usage is metered by plan (see Plans & Limits). Rate limits by credential are in Rate Limits & Errors.