# Authentication

> Authenticate Public API V1 requests with scoped CreatorsJet API keys.
>
> Canonical URL: https://docs.creatorsjet.com/api/authentication

The Public API uses scoped Bearer API keys. Session JWTs, browser sessions, and MCP OAuth tokens are not accepted under `/public/v1`.

## Authorization header

Send the complete key on every request:

```http
Authorization: Bearer cj_live_<public-id>.<secret>
```

The secret is a 32-byte base64url value. Treat the entire key as sensitive even though the public ID and display prefix remain visible in settings.

## Key ownership and eligibility

| Subject | Who manages keys                          | Plan requirement                 |
| ------- | ----------------------------------------- | -------------------------------- |
| Creator | The signed-in user linked to that creator | Active Pro                       |
| Agency  | Any current agency owner                  | Active Pro, Scale, or Enterprise |

Entitlement and subject ownership are checked on every API request. A plan downgrade disables requests without deleting the key. Current agency owners can manage keys owned by their agency.

## Scopes

| Scope               | Creator keys | Agency keys | Grants                                                                    |
| ------------------- | -----------: | ----------: | ------------------------------------------------------------------------- |
| `profile:read`      |          Yes |          No | Read the creator subject's own profile summary                            |
| `roster:read`       |           No |         Yes | List and retrieve creators in the agency roster and inspect import status |
| `roster:write`      |           No |         Yes | Add creators and start CSV imports                                        |
| `media_kits:read`   |          Yes |         Yes | List and retrieve visible owned media kits                                |
| `media_kits:write`  |          Yes |         Yes | Ensure the subject's default media kit exists                             |
| `link_in_bio:read`  |          Yes |          No | Retrieve the creator subject's link-in-bio page                           |
| `link_in_bio:write` |          Yes |          No | Create or edit the creator subject's link-in-bio page                     |
| `decks:read`        |           No |         Yes | List and retrieve pitch decks owned by the agency subject                 |
| `decks:write`       |           No |         Yes | Create or edit pitch decks owned by the agency subject                    |
| `campaigns:read`    |          Yes |         Yes | List and retrieve campaigns owned by the subject                          |
| `campaigns:write`   |          Yes |         Yes | Create or edit campaigns owned by the subject                             |
| `analytics:read`    |          Yes |         Yes | Read page views and unique visitors for resources owned by the subject    |

`sponsorships:read` is reserved for future compatibility and cannot be selected for a V1 API key.

Create separate keys for integrations with different responsibilities. Do not give a read-only integration write scopes.

## Lifecycle

* A subject can have at most 10 active keys.
* A key can have no expiration or expire after 30, 90, or 365 days.
* The complete secret appears only when the key is created.
* Revocation is immediate and permanent.
* Rotation is create a replacement, deploy it, verify it, then revoke the previous key.
* `last_used_at` is updated at most once every 15 minutes, so it is an activity indicator rather than a request log.

## Secret handling

* Keep API keys in a server-side secret manager or protected environment variable.
* Never expose a key through browser JavaScript, mobile binaries, screenshots, support messages, analytics, or source control.
* Redact `Authorization` before logging requests.
* Revoke and replace a key immediately if it may have been exposed.

Malformed, expired, revoked, or incorrect keys return `401 INVALID_API_KEY`. A missing credential returns `401 AUTHENTICATION_REQUIRED`.