Authentication¶

Carver Horizon supports two authentication methods depending on the API version.

Base URL

All API endpoints are served at https://app.carveragents.ai.

V1 API — X-API-Key¶

Pass your API key in the X-API-Key header:

GET /api/v1/feeds/entries/
Host: your-domain.com
X-API-Key: your-api-key-here

Generate keys from Admin Dashboard → Settings → API Keys.

Key Rotation¶

Rotate your API key from the Admin Dashboard. Old keys are immediately invalidated on rotation.

V2 API — JWT Bearer (Firebase)¶

The V2 API requires a Firebase JWT token:

GET /api/v2/feeds/
Host: your-domain.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Obtaining a Token¶

import { getAuth, signInWithEmailAndPassword } from "firebase/auth";

const auth = getAuth();
const userCredential = await signInWithEmailAndPassword(auth, email, password);
const token = await userCredential.user.getIdToken();

Tokens expire after 1 hour. Use Firebase's token refresh mechanism to maintain sessions.

Choosing Between V1 and V2¶

	V1 (X-API-Key)	V2 (JWT Bearer)
Use case	Server-to-server	User-facing apps
Auth type	Static key	Firebase JWT
Per-user access	No	Yes
RBAC	No	Yes
Expiry	Never	1 hour

Python SDK Authentication¶

The carver-feeds-sdk uses V1 API key authentication. Configure credentials via environment variables:

# .env
CARVER_API_KEY=your_api_key_here
CARVER_BASE_URL=https://app.carveragents.ai  # optional, this is the default

The SDK automatically loads these when you call any factory function:

from carver_feeds import get_client

client = get_client()  # reads CARVER_API_KEY from environment

For explicit configuration without a .env file:

from carver_feeds import CarverFeedsAPIClient

client = CarverFeedsAPIClient(api_key="your_api_key_here")