Authentication

All requests to the Flowstate API must include a valid API key. Keys are created in the Flowstate UI and scoped to specific permissions.

API Key Format

API keys follow a structured format:

private_{identifier}_{secret}

Segment	Description
private_	Prefix indicating this is a secret key
{identifier}	Short alphanumeric ID used for key lookup
{secret}	Cryptographically random string (the secret)

Example:

private_k1a2b3c4_xYz987AbCdEfGhIjKlMnOpQrStUv

Including the Key in Requests

Pass the API key in the Authorization header using the Bearer scheme:

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/employees" \
  -H "Authorization: Bearer private_k1a2b3c4_xYz987AbCdEfGhIjKlMnOpQrStUv"

WARNING

Do not include API keys in query parameters or request bodies. The Authorization header is the only supported method.

Creating API Keys

1. Navigate to Settings > API Keys in the Flowstate UI
2. Click Create API Key
3. Enter a descriptive name (e.g., "Workday Sync", "BI Dashboard")
4. Select the required permission scopes (see below)
5. Click Create
6. Copy the key immediately — it is shown only once

Permission Scopes

Each API key is scoped to a specific set of permissions. This follows the principle of least privilege: grant only the access each integration needs.

Scope	Description
employees:read	List and retrieve employee records
employees:write	Create, update, and delete employees
contractors:read	List and retrieve contractors
contractors:write	Create, update, and delete contractors
vacancies:read	List and retrieve vacancies
vacancies:write	Create, update, and delete vacancies
teams:read	List and retrieve teams
teams:write	Create, update, and delete teams
projects:read	List and retrieve projects
projects:write	Create, update, and delete projects
assignments:read	List and retrieve assignments
assignments:write	Create, update, and delete assignments
cost-centres:read	List and retrieve cost centres
cost-centres:write	Create, update, and delete cost centres
value-streams:read	List and retrieve value streams
value-streams:write	Create, update, and delete value streams
work-types:read	List and retrieve work types
work-types:write	Create, update, and delete work types
drivers:read	List and retrieve drivers
drivers:write	Create, update, and delete drivers
lifecycle-stages:read	List and retrieve lifecycle stages
lifecycle-stages:write	Create, update, and delete lifecycle stages
exchange-rates:read	List and retrieve exchange rates
exchange-rates:write	Create, update, and delete exchange rates
locations:read	List and retrieve locations
locations:write	Create, update, and delete locations

Key Lifecycle

• Maximum lifetime: API keys expire after 90 days from creation. You must rotate keys before expiration to avoid service disruption.
• Revocation: You can revoke a key at any time from Settings > API Keys. Revocation is immediate — all subsequent requests with that key will return 401 Unauthorized.
• Rotation: Create a new key before revoking the old one to ensure zero downtime.

Security Best Practices

TIP

Follow these guidelines to keep your integration secure.

1. Rotate keys regularly — Do not wait for the 90-day expiration. Rotate keys every 30-60 days.
2. Use minimal permissions — Only grant the scopes your integration actually needs. A reporting dashboard needs read scopes, not write.
3. Never commit keys to source control — Store API keys in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.).
4. Use separate keys per integration — If you have three systems connecting to Flowstate, create three separate keys. This way you can revoke one without affecting the others.
5. Monitor key usage — Check the API Keys settings page periodically for keys that are unused or approaching expiration.
6. Restrict network access — If your integration runs from a known set of IP addresses, consider using network-level controls in addition to API key authentication.

Error Responses

If authentication fails, the API returns:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "errorId": "err_abc123"
  }
}

HTTP Status	Meaning
401	Missing, invalid, or expired API key
403	Valid key but insufficient permissions