Authentication

API keys, supporter subscriptions and rate limits.

Every endpoint takes an API key in the Authorization header:

Authorization: Bearer sc_...

The app's own login tokens are not API keys. Sending one gets the same 401 as a wrong key.

Keys

Users create keys in the app under Settings → Integrations → API. The full key is shown once, then only its hash is kept server-side. They can also see each key's label, creation date and last use, and revoke it from the same place.

An account holds at most 3 active keys. Revoking one frees the slot.
Keys start with sc_. Older keys start with drk_ and keep working. The server authenticates keys by their hash.
Revoked or wrong key: 401 {"error": "unauthorized", "message": "invalid API key"}.
No header at all: 401 with the message missing API key (Authorization: Bearer sc_...).
The key label appears in the app's last-trigger feed as api:<label>, so a label like your product name helps the user recognise you.

Supporter subscription

Every endpoint except GET /relay/me requires an active supporter subscription on the key's account, managed at account.kinkyraven.com. Verified creator accounts count as supporters. Without either you get:

{"error": "patreon_required", "message": "the API requires an active supporter subscription on the linked account"}

The status is 403. The code keeps its historical name for compatibility, so match on patreon_required even though Patreon is only one of the payment routes.

GET /relay/me is exempt. It reports subscription status as patreon.active, so you can distinguish an inactive subscription from an invalid key.

The key owner needs a subscription for friend calls. The friend does not need one to receive commands, but premium effects and remote sequences still require the relevant entitlement on their account.

Rate limits

Each authenticated call counts towards two limits in fixed 60-second windows:

120 requests per minute per key.
240 requests per minute per account, all keys summed.

Trigger calls count towards the same limits. Exceeding either limit returns:

{"error": "rate_limited", "message": "API rate limit exceeded", "retryAfter": 47}

The status is 429 and the same number arrives as a Retry-After header, in seconds until the window resets. GET /relay/me returns used_this_window so you can watch the counters, and the call itself counts.

Friend endpoints have additional rate limits. They are listed per endpoint.

Invalid-key attempts are also limited to 30 per IP in 10 minutes. Stop using a key after a 401 until the user supplies a valid one.

# Authentication

API keys, supporter subscriptions and rate limits.

Every endpoint takes an API key in the Authorization header:

```
Authorization: Bearer sc_...
```

The app's own login tokens are not API keys. Sending one gets the same `401` as a wrong key.

## Keys

- An account holds at most 3 active keys. Revoking one frees the slot.
- Keys start with `sc_`. Older keys start with `drk_` and keep working. The server authenticates keys by their hash.
- Revoked or wrong key: `401 {"error": "unauthorized", "message": "invalid API key"}`.
- No header at all: `401` with the message `missing API key (Authorization: Bearer sc_...)`.
- The key label appears in the app's last-trigger feed as `api:<label>`, so a label like your product name helps the user recognise you.

## Supporter subscription {#supporter-gate}

Every endpoint except `GET /relay/me` requires an active supporter subscription on the key's account, managed at account.kinkyraven.com. Verified creator accounts count as supporters. Without either you get:

```json
{"error": "patreon_required", "message": "the API requires an active supporter subscription on the linked account"}
```

The status is `403`. The code keeps its historical name for compatibility, so match on `patreon_required` even though Patreon is only one of the payment routes.

`GET /relay/me` is exempt. It reports subscription status as `patreon.active`, so you can distinguish an inactive subscription from an invalid key.

## Rate limits

Each authenticated call counts towards two limits in fixed 60-second windows:

- 120 requests per minute per key.
- 240 requests per minute per account, all keys summed.

Trigger calls count towards the same limits. Exceeding either limit returns:

```json
{"error": "rate_limited", "message": "API rate limit exceeded", "retryAfter": 47}
```

The status is `429` and the same number arrives as a `Retry-After` header, in seconds until the window resets. `GET /relay/me` returns `used_this_window` so you can watch the counters, and the call itself counts.

Friend endpoints have additional rate limits. They are listed per endpoint.

Invalid-key attempts are also limited to 30 per IP in 10 minutes. Stop using a key after a `401` until the user supplies a valid one.