Authentication
How to authenticate a request to any Flourish product API.
Overview
Every Flourish product that exposes an API is served from one host and uses one authentication scheme. Learn it once and it applies everywhere, whether you are generating a PDF, calling 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.
Base URL
https://api.toflourish.org
Paths are namespaced by product, so the Impression PDF Build endpoint is:
https://api.toflourish.org/impression/pdf-build
Each endpoint's own page gives its full path, 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.
Your Flourish contact issues the organization identifier, the token, and the environment values that apply to you.
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.