Authentication

Create and use a workspace-pinned Floral personal access token.

External integrations authenticate with a Floral personal access token. Each token is pinned to the user, organization, and workspace that created it, and its scopes can only narrow that user’s existing access.

Create a token

1. Open your workspace in Floral.
2. Go to Settings → Agents.
3. Enable Floral Agent if a workspace administrator has not enabled it.
4. Create a personal access token, select its scopes, and choose an expiry.
5. Copy the token when it is shown. Floral stores only its hash and cannot display the plaintext again.

Choose the narrowest scopes your integration needs:

Scope	Access
contacts:read	Search companies and people, load their details, and query the company registry.
contacts:write	Create and change companies and people.
meetings:read	List and read briefings and meeting summaries.
meetings:write	Generate briefings, replace summary notes, and approve eligible summaries.

Some operations require more than one scope. For example, briefing generation requires meetings:write and contacts:read. The API reference lists the exact scopes on every operation.

Treat a personal access token like a password. Store it in a secret manager, never commit it, and revoke it from Floral when it is no longer needed.

Send the token

Pass the token as a bearer credential:

curl --get --url "https://app.floral.so/api/v1/workspaces/your-workspace/relationships/search" \
  --data-urlencode "q=Acme" \
  --header "Authorization: Bearer $FLORAL_TOKEN"

A token cannot access a different workspace by changing the slug in the URL. Floral also reloads active membership and feature access on every request, so removing a user’s access takes effect without rotating the token.

Authentication failures

An invalid, expired, or revoked token returns 401 UNAUTHENTICATED. A valid token without the required scope returns 403 FORBIDDEN. A valid token used with another workspace is rejected without exposing cross-workspace data.

Scope checks do not replace feature, role, or resource checks. A token cannot grant more access than its owner has in the selected workspace.