Authentication and API keys

What a key looks like

A key reads fw_test_ or fw_live_, followed by a random secret of 40 letters and digits. Its first 12 characters (fw_live_AbCd) are its prefix: that is how we refer to a key when we talk with you.

Floweet only keeps the fingerprint (SHA-256) of the full key. It is therefore shown to you once, when it is created; if lost, it cannot be recovered: a new one must be created.

One organization, one designated member

A key belongs to a Floweet organization and acts for one ADMIN member of that organization, designated when the API account is opened. It sees and changes exactly what that member can see and change in the application, under the same rules and with the organization's plan: no more, no less. A resource of another organization answers 404 not_found, as if it did not exist.

A module the organization's plan does not include answers 403 plan_required (see plans and AI). If the designated member leaves the organization or loses the ADMIN role, calls answer 403 account_misconfigured until another member is designated. All the keys of an organization share its rate limits; it may hold at most 10 active keys.

Test keys and live keys

Keep the key secret

• Call the API from your server. Store the key in an environment variable or a secrets vault, never in a code repository.
• Never in a web page or a mobile app: the API does not answer browsers' CORS requests, on purpose. An exposed key must be revoked.
• One key per application and per environment: if one leaks, you only revoke that one.
• Give each key the fewest scopes it needs: a dashboard only needs reads.

Rotating or revoking a key

To rotate a key without downtime: ask for a new one, deploy it, then ask us to revoke the old one. A revoked key stops working within a minute (keys are re-read every 30 seconds at most) and then answers 401 api_key_revoked. When an account leaves production, its live keys are revoked.

These steps are done by e-mail today, at contact@floweet.com; they will move to the developer space Coming soon.

Authentication errors

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key. Add the header “Authorization: Bearer fw_live_…”."
  }
}

• 401 invalid_api_key: missing or malformed header, or unknown key.
• 401 api_key_revoked: the key has been revoked.
• 403 live_not_enabled: live key of an API account not yet opened for production.
• 403 account_suspended: API access suspended for this organization.
• 403 account_misconfigured: the designated member is no longer an ADMIN of the organization.
• 403 insufficient_scope: the key lacks the operation's scope (see scopes).

The message follows the Accept-Language header (French without it); your code relies on code. See errors.