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 → Users & Access → API Keys (/settings/access/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 permissions the key needs (see below)
5. Click Create
6. Copy the key immediately — it is shown only once

Permissions

API keys do not use their own scope system. Each key is granted a set of permissions from the same permission model as user roles. When you create a key, you pick the specific permissions it should hold from a checklist grouped by category. Every request made with the key is authorised against those granted permissions.

Follow the principle of least privilege: grant only the access each integration needs. A reporting dashboard needs view permissions only. A sync integration needs create and update permissions for the entities it pushes, but nothing else.

See API key security for the full permission reference and lifecycle details.

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 → Users & Access → 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 permissions your integration actually needs. A reporting dashboard needs view permissions, not create or update.
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