Authentication & API Keys

Every API request to Catalogian requires authentication via an API key. This page covers key types, scopes, how to create and rotate keys, and security best practices.

Key types

Catalogian has two types of API keys:

Type	Prefix	Scope	Use case
Account key	`cat_live_`	Access all sources in your account	Backend services, CI/CD, admin scripts
Source-scoped key	`cat_src_`	Access a single source only	Share with vendors, embed in agents, limited-access integrations

Using keys

Pass the key in the Authorization header:

curl https://api.catalogian.com/v1/sources \
  -H "Authorization: Bearer cat_live_your_key_here"

Source-scoped key behavior

When using a source-scoped key (cat_src_), the source is resolved automatically. You don't need to pass a source ID — or you can use the source's slug:

# These are equivalent with a source-scoped key:
GET /v1/sources
GET /v1/sources/my-product-feed/delta/latest

GET /v1/sources with a source-scoped key returns only the scoped source — not all sources in the account.

Scopes

Scope	Available on	Permissions
`full`	Account keys only	Read + write access to all endpoints (create sources, manage keys, etc.)
`read`	Both	Read sources, delta events, and snapshot metadata
`download`	Both	Export snapshot data as CSV/JSON files

The delta rows endpoint (full row data with before/after values) requires read scope on account keys or any scope on source-scoped keys.

Creating keys

Via the dashboard

Go to Settings → API Keys to create account-level keys, or Source → Settings → API Keys for source-scoped keys.

Via the API

# 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 source-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 only shown once in the response. It is stored as a SHA-256 hash and cannot be retrieved later.

Revoking keys

# Revoke an account key
DELETE /v1/apikeys/:keyId

# Revoke a source-scoped key
DELETE /v1/sources/:id/apikeys/:keyId

Revoked keys stop working immediately. There is no way to un-revoke a key — create a new one instead.

Key rotation best practices

•Create before you revoke. Create the new key, update your integration, verify it works, then revoke the old key.
•Use descriptive names. Name keys after their use case (e.g. "CI Pipeline", "Webhook Processor") so you know which to revoke.
•Prefer source-scoped keys for integrations that only need access to a single source. This limits blast radius if a key leaks.
•Never commit keys to version control. Use environment variables or a secrets manager.

Plan requirements

API keys require Brand plan or higher. Free (Starter) accounts can access the dashboard and MCP (50 calls/day) but cannot create API keys.

Understand rate limits and error codes. Rate Limits & Errors →