Authentication

FeatureOS authenticates every API request with the unique API key tied to your organization. A request without authentication, or with an invalid key, returns 401 — API key is invalid. A request with a valid key but insufficient permissions returns 403 — Insufficient permissions.

API keys

Pass your API key in the API-KEY header on every request:

curl https://api.featureos.app/api/v3/buckets \
  -H 'API-KEY: hn_your_api_key'

You can view and manage your API keys in the FeatureOS dashboard. See the help article on generating an API key for step-by-step instructions.

Note — Since November 30, 2022, all API keys begin with the hn_ prefix.

Securing your API keys

Your API keys can perform read and write operations on your FeatureOS account. In the wrong hands they can cause destructive, data-losing actions. Keep them safe:

• Never expose API keys in public or client-side code.
• Do not commit keys to version control that others can access.
• If a key is exposed, hit the kill-switch — regenerate the key from your account and update your app accordingly.

Warning — All requests must be made over HTTPS. Any request made over plain HTTP is rejected by our servers.

Acting on behalf of a user

Some write operations act on behalf of a specific end user — for example, creating a post or vote "on behalf" of a customer. These require a user-specific JWT in the Authorization header, in addition to your API-KEY. This is the same SSO token used by the widget, generated from your organization's SSO key.

curl -X POST https://api.featureos.app/api/v3/feature_requests/post_on_behalf \
  -H 'API-KEY: hn_your_api_key' \
  -H 'Authorization: Bearer <user_sso_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "title": "Dark mode", "bucket_id": 1 }'

See the help article on setting up single sign-on for how to mint these tokens.

Rate limiting

The API allows 100 requests per minute per API key. Exceeding it returns 429 Too Many Requests. See Errors for the full list of status and application error codes.