Authenticate Requests to the Feather Platform API

Feather authenticates every API request using API keys that you create and manage inside your organization. There are no session cookies or OAuth flows required — include your key on every request and Feather verifies your identity, organization membership, and permission scopes automatically.

Passing Your API Key

Pass your key in the x-api-key request header on every request. This is the only supported authentication method — Feather does not accept Bearer tokens, session cookies, or OAuth credentials.

curl https://api-sandbox.featherhq.com/v1/identity/whoami \
  -H 'x-api-key: fth_live_xxxxxxxxxxxxxxxxxxxx'

API keys do not expire by default. If you need time-bounded access — for example for a contractor or a CI pipeline — set the expires_at field when you create the key.

Creating an API Key

Call POST /v1/identity/api-keys to create a new key. You can optionally assign a list of permission scopes and an expiry date.

The plain_text_key value is returned only once, at creation time. Copy it to a secure secret store immediately. Feather never exposes the full key again — you can only see its prefix afterward.

Send the creation request

POST to /v1/identity/api-keys with a JSON body that includes a human-readable name. Add scopes and expires_at if needed.

curl -X POST https://api-sandbox.featherhq.com/v1/identity/api-keys \
  -H 'x-api-key: fth_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-app-key",
    "scopes": ["conversations:read", "conversations:manage", "assistants:read"],
    "expires_at": "2026-01-01T00:00:00Z"
  }'

Store the plain-text key immediately

The response includes a plain_text_key field containing the full secret. Save it to your environment variables or secrets manager before you close the response.

Response (201 Created)

{
  "id": "ak_01hwqz3k9fmxp7v2brgnte8cja",
  "name": "my-app-key",
  "plain_text_key": "fth_live_4T8zQrVnLwJpKsYdXcMbUeAoHiFgNt",
  "key_prefix": "fth_live_4T8z",
  "scopes": ["conversations:read", "conversations:manage", "assistants:read"],
  "is_active": true,
  "last_used_at": null,
  "expires_at": "2026-01-01T00:00:00Z",
  "created_at": "2025-01-15T10:32:00Z"
}

Request Body Fields

string

required

A human-readable label for the key. Useful for identifying which application or team member owns it.

string[]

An optional list of permission scopes that limit what the key can do. Omitting this field grants the key all permissions available to your organization role.

string (ISO 8601)

An optional expiry timestamp in ISO 8601 format (e.g. 2026-01-01T00:00:00Z). The key becomes inactive after this time. Omit to create a non-expiring key.

API Key Response Schema

string (UUID)

Unique identifier for the API key. Use this to list or revoke the key later.

string

The human-readable label you provided at creation.

string

The full secret key value. Present only in the creation response. Store it immediately — Feather will never return it again.

string

The first few characters of the key (e.g. fth_live_4T8z). Shown in listing endpoints so you can identify which key is which without exposing the full secret.

string[]

The permission scopes assigned to this key.

boolean

true while the key is usable. Becomes false after the key is revoked or its expires_at time has passed.

string (ISO 8601) | null

The timestamp of the most recent authenticated request made with this key. null if the key has never been used.

string (ISO 8601) | null

The expiry time you set at creation, or null if the key has no expiry.

string (ISO 8601)

The timestamp when the key was created.

Listing and Revoking Keys

List All Keys

Retrieve all active API keys in your organization. The response includes key_prefix so you can identify each key without exposing the full secret.

curl https://api-sandbox.featherhq.com/v1/identity/api-keys \
  -H 'x-api-key: fth_live_xxxxxxxxxxxxxxxxxxxx'

Response (200 OK)

{
  "data": [
    {
      "id": "ak_01hwqz3k9fmxp7v2brgnte8cja",
      "name": "my-app-key",
      "key_prefix": "fth_live_4T8z",
      "scopes": ["conversations:read", "conversations:manage", "assistants:read"],
      "is_active": true,
      "last_used_at": "2025-01-20T08:14:32Z",
      "expires_at": "2026-01-01T00:00:00Z",
      "created_at": "2025-01-15T10:32:00Z"
    },
    {
      "id": "ak_01hx4m8rtnbqe0wjyp5vugc3sf",
      "name": "ci-pipeline",
      "key_prefix": "fth_live_9Kc2",
      "scopes": ["assistants:read"],
      "is_active": true,
      "last_used_at": "2025-01-21T03:00:11Z",
      "expires_at": null,
      "created_at": "2025-01-10T09:00:00Z"
    }
  ]
}

Revoke a Key

Send a DELETE request with the key’s id to permanently revoke it. Revocation is immediate — any in-flight request using that key after this point will receive a 401 error.

curl -X DELETE https://api-sandbox.featherhq.com/v1/identity/api-keys/ak_01hwqz3k9fmxp7v2brgnte8cja \
  -H 'x-api-key: fth_live_xxxxxxxxxxxxxxxxxxxx'

A successful revocation returns 204 No Content with an empty response body.

Rate limits

Feather applies a per-organization rate limit across the API — 6,000 requests per minute. The limit is shared by every key in the organization, not per key. When you exceed it, Feather returns 429 Too Many Requests. Back off and retry after a short delay; batch or space out high-volume workloads to stay under the limit.

429 Too Many Requests

{
  "error": "rate_limited",
  "message": "Organization rate limit exceeded. Retry after a short delay."
}

Error Responses

401 — Authentication Required

Returned when the API key is missing, malformed, revoked, or expired.

401 Authentication Required

{
  "error": "authentication_required",
  "message": "No valid API key was provided. Pass your key in the x-api-key header."
}

400 — Bad Request

Returned when the request body is missing required fields or contains an invalid value (for example, a malformed expires_at timestamp).

400 Bad Request

{
  "error": "bad_request",
  "message": "The value provided for 'expires_at' is not a valid ISO 8601 datetime string."
}

Get Started

Core Concepts

Guides

Channels

Authenticate Requests to the Feather Platform API

Passing Your API Key

Creating an API Key

Request Body Fields

API Key Response Schema

Listing and Revoking Keys

List All Keys

Revoke a Key

Rate limits

Error Responses

401 — Authentication Required

400 — Bad Request

​Passing Your API Key

​Creating an API Key

​Request Body Fields

​API Key Response Schema

​Listing and Revoking Keys

​List All Keys

​Revoke a Key

​Rate limits

​Error Responses

​401 — Authentication Required

​400 — Bad Request

Passing Your API Key

Creating an API Key

Request Body Fields

API Key Response Schema

Listing and Revoking Keys

List All Keys

Revoke a Key

Rate limits

Error Responses

401 — Authentication Required

400 — Bad Request