export const metadata = {
  title: "Authentication",
  description:
    "Create API keys, rotate credentials, and authenticate requests to the FaithTranscripts API.",
  alternates: { canonical: "/docs/api/authentication" },
};

# Authentication

Every API request must authenticate with a Bearer token. Tokens are issued per
organization from the dashboard and belong to exactly one org — all
resources you create are owned by that org.

## Get a key

Any member of your organization can mint an API key.

1. Sign in to the dashboard.
2. Navigate to [Settings → API Keys](/settings/api-keys).
3. Click **Create API key**, give it a recognizable label (e.g. `production-server`), and click **Create**.
4. Copy the revealed `ft_live_…` value. You can reveal it again from the list at any time.

<Callout variant="tip">
  Keys are recoverable. Unlike many other APIs, FaithTranscripts lets you reveal
  the full key value again from the dashboard whenever you need it. We accept
  the tradeoff for lower operational friction.
</Callout>

## Send the key

Send the key as a Bearer token in the `Authorization` header.

```bash
curl https://www.faithtranscripts.com/api/v1/me \
  -H "Authorization: Bearer ft_live_YOUR_KEY"
```

The `ft_live_` prefix makes the secret greppable in logs and lets scanners
(GitHub, GitGuardian) recognize it if it's ever exposed. Don't strip it.

## What a key can do

An API key has the same permissions on transcript resources that a signed-in
org member has:

- Create, read, list, and delete transcripts for its org
- Trigger AI validation passes

What it **cannot** do:

- Manage API keys (dashboard session required)
- Change organization, billing, or member settings

## Rotation

There's no rotation endpoint. If a key leaks, delete it from the dashboard
and mint a new one. Deleting a key is immediate — any integration still
using it will get `401 unauthorized` on its next request.

## Expiration

You can set an optional expiration date when creating a key. After that
date, requests using it will receive `401 unauthorized`. Keys without an
expiration live until they're deleted.

## Errors

Requests with a missing, malformed, or expired key return:

```json
{
  "error": {
    "type": "unauthorized",
    "message": "Invalid or missing API key.",
    "request_id": "req_01HW..."
  }
}
```

Next: [Quickstart](/docs/api/quickstart).