Authentication
How to authenticate a request to any Flourish product API.
Overview
Flourish product APIs share one authentication scheme. Learn it once and it applies everywhere, whether you are generating a PDF, invoking an agent, or enriching a record.
Authentication is by header. There are no API keys in the query string, no OAuth flow, and no session to establish first. You send your credentials on every request.
Hosts
There is more than one, so check the page for the endpoint you are calling rather than assuming.
| Host | Serves |
|---|---|
https://api.toflourish.org | Most product endpoints, namespaced by product, such as Impression PDF Build at /impression/pdf-build. |
https://agentplatform.toflourish.org | The Agent Platform, including the Daemon at /api/agents/{agent_id}/invoke. |
Each endpoint's own page gives its full URL, its request body, and what it returns.
Headers
| Header | Required | Purpose |
|---|---|---|
fl-api-org | Always | Identifies your organization. |
fl-api-token | Always | Your API token. |
fl-api-env | Some endpoints | Selects the environment the request runs against. |
fl-api-org and fl-api-token go on every request. Treat that as the rule. If an endpoint is one of the rare exceptions, its own page says so.
fl-api-env is per endpoint. Some need it and some do not, so check the page for the endpoint you are calling rather than assuming. Sending it where it is not needed is harmless; leaving it off where it is required is not. Every Agent Platform endpoint requires it, and its values are environment names such as prod and dev.
Your Flourish contact issues the organization identifier, the token, and the environment values that apply to you.
Permissions are per agent or per resource, not carried by the token alone. A token that authenticates successfully can still be refused with 403 on something it has no grant for.
A complete request
curl -X POST https://api.toflourish.org/impression/pdf-build \
-H "Content-Type: application/json" \
-H "fl-api-org: YOUR_ORG" \
-H "fl-api-token: YOUR_TOKEN" \
-H "fl-api-env: YOUR_ENV" \
-d '{
"screens": [
{ "id": "page1", "blocks": [
{ "type": "text", "x": 20, "y": 20, "width": 170, "value": "Hello, world." }
]}
],
"document": { "unit": "mm", "screens": ["page1"] }
}'
Request and response bodies are JSON throughout.
Keeping your token safe
Your token authenticates as your organization, so anything holding it can act as you.
- Call from your server, never from a browser. A token in page source, in client-side JavaScript, or in a mobile app binary is a published token, whatever else the page does to hide it.
- Keep it out of source control. Use an environment variable or your platform's secret store.
- Don't put it in a URL. Query strings end up in server logs, proxy logs, and browser history in a way headers do not.
- Tell us promptly if one is exposed so it can be replaced.
This is also why the embed snippets for the Chatbot and for Chronicle forms carry no token. They run on a visitor's page, where a secret cannot be kept, so they identify themselves a different way.