Authentication

The Feathr API authenticates every request with an opaque API key presented as a bearer token.

Authorization: Bearer fthr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys

• Shown once. The key is displayed only at creation and cannot be retrieved afterward — Feathr never stores the secret itself. If you lose it, revoke it and mint a new one.
• Account-scoped. A key authenticates as exactly one Feathr account; every request acts on that account's data.
• Revocable. Revoking a key takes effect immediately — subsequent requests with it are rejected.

Scopes

Each key carries a set of scopes of the form resource:action, for example:

Scope	Grants
persons:read	Read persons and their fields
persons:write	Create and update persons
tags:read	Read tags
tags:write	Create, update, and delete tags
campaigns:read	Read campaigns
projects:read	Read projects

An endpoint declares the scope it requires. A key without that scope is rejected with 403 Forbidden even though it authenticated successfully. Grant each key the least privilege its integration needs.

Use GET /me to see the scopes attached to the key you are using.

Error responses

Authentication and authorization failures are returned as RFC 7807 problem documents (application/problem+json):

Status	Meaning
401 Unauthorized	Missing, malformed, unknown, revoked, or expired key.
403 Forbidden	The key is valid but lacks a scope the endpoint requires.
429 Too Many Requests	The key exceeded its per-minute rate limit.

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Key is missing required scope: persons:write"
}

Rate limiting

Requests are rate limited per key. When you exceed the limit you receive a 429 problem document; back off and retry after a short delay.