Authentication

TPC resolves callers in a fixed order: API key, bearer token, then session cookie. If you send more than one credential, x-api-key wins.

Choose your credential

Credential	Best for	Notes
Session cookie	First-party dashboard calls.	Browser-only. Session callers rely on route-level organization and product checks.
OAuth bearer	CLI and OAuth clients.	`tpc auth login` uses a browser device flow, then the CLI sends bearer credentials.
API key	Server-to-server integrations.	Organization-scoped, rotatable, and limited by explicit scopes.

Session cookies are for The Prompting Company dashboard. The browser sends the better-auth.session_token cookie automatically.

curl "https://app.promptingco.com/api/v1/site/pages?productId=product_123" \
  -H "Cookie: better-auth.session_token=session_token_here"

const response = await fetch("/api/v1/site/pages?productId=product_123", {
  credentials: "include",
});

Use session cookies only for first-party browser flows.

OAuth bearer

The CLI authenticates with browser-based device flow:

tpc auth login

After login, the CLI stores a local token and sends it as a bearer credential:

curl "https://app.promptingco.com/api/v1/site/pages?productId=product_123" \
  -H "Authorization: Bearer $TPC_ACCESS_TOKEN"

const response = await fetch(
  "https://app.promptingco.com/api/v1/site/pages?productId=product_123",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);

Bearer callers must include the scopes required by the route.

API key

API keys are the recommended credential for integrations. Create an organization API key from:

https://app.promptingco.com/{orgSlug}/settings/api-keys

Then send it with x-api-key:

curl "https://app.promptingco.com/api/v1/site/pages?productId=product_123" \
  -H "x-api-key: $TPC_API_KEY"

const response = await fetch(
  "https://app.promptingco.com/api/v1/site/pages?productId=product_123",
  {
    headers: {
      "x-api-key": process.env.TPC_API_KEY!,
    },
  },
);

Precedence

resolveCaller checks credentials in this order:

x-api-key
Authorization: Bearer <token>
Session cookie

That precedence makes server integrations deterministic. If a background job accidentally includes a browser cookie, the API key still identifies the integration.

Rotation and revocation

Rotate API keys when a teammate leaves, a secret may have leaked, or an integration boundary changes.

Create a new key with the same or narrower scopes.
Deploy the new secret to your integration.
Confirm requests are succeeding with the new key.
Revoke the old key from the API key settings page.

Revoked keys fail with:

{
  "ok": false,
  "code": "UNAUTHORIZED",
  "message": "invalid api key"
}

Get started

Concepts

Content API

API Reference

Authentication

Authentication

Choose your credential

OAuth bearer

API key

Precedence

Rotation and revocation

​Authentication

​Choose your credential

​Session cookie

​OAuth bearer

​API key

​Precedence

​Rotation and revocation

Authentication

Choose your credential

Session cookie

OAuth bearer

API key

Precedence

Rotation and revocation