API Keys

API keys authenticate programmatic access to the Flowstate REST API. Each key is scoped to specific entity permissions so you can grant exactly the access each integration needs, and nothing more.

Overview

Flowstate uses a structured key format that supports efficient lookup and secure validation without exposing the full secret in logs, the UI, or database records.

Key Format

private_{identifier}_{secret}

Segment	Description
`private_`	Fixed prefix indicating this is a secret API key
`{identifier}`	Short alphanumeric ID used for O(1) key lookup (no full-table scan needed)
`{secret}`	Cryptographically random string, SHA-256 hashed before storage

Example:

private_k1a2b3c4_xYz987AbCdEfGhIjKlMnOpQrStUv

The full key is shown only once at creation time. Flowstate stores a key prefix (e.g., private_k1a2b3c...) for display purposes in the UI, alongside the hashed secret. The raw secret is never persisted.

DANGER

Copy your API key immediately after creation. Flowstate cannot retrieve or display the full key again. If you lose the key, you must revoke it and create a new one.

Creating API Keys

Navigate to Settings > API Keys
Click Create API Key
Enter a descriptive name (e.g., "Workday Sync", "BI Dashboard", "CI Pipeline")
Select the required permission scopes
Click Create
Copy the key immediately -- it is shown only once

Creating API keys requires the SETTINGS_API_KEYS_CREATE permission.

Permission Scopes

Each API key is scoped to a specific set of entity permissions. Every scope has a :read and :write variant, so you can grant read-only or full access per entity type.

Scope	Read Access	Write Access
`employees`	List and retrieve employee records	Create, update, and delete employees
`contractors`	List and retrieve contractors	Create, update, and delete contractors
`vacancies`	List and retrieve vacancies	Create, update, and delete vacancies
`teams`	List and retrieve teams	Create, update, and delete teams
`projects`	List and retrieve projects	Create, update, and delete projects
`assignments`	List and retrieve assignments	Create, update, and delete assignments
`cost-centres`	List and retrieve cost centres	Create, update, and delete cost centres
`value-streams`	List and retrieve value streams	Create, update, and delete value streams
`work-types`	List and retrieve work types	Create, update, and delete work types
`drivers`	List and retrieve drivers	Create, update, and delete drivers
`lifecycle-stages`	List and retrieve lifecycle stages	Create, update, and delete lifecycle stages
`exchange-rates`	List and retrieve exchange rates	Create, update, and delete exchange rates
`locations`	List and retrieve locations	Create, update, and delete locations

TIP

Follow the principle of least privilege. A reporting dashboard only needs :read scopes. A sync integration that pushes data into Flowstate needs :write scopes for the relevant entities, but probably does not need access to every entity type.

Key Lifecycle

API keys have a defined lifecycle from creation through expiration or revocation.

Expiration

Every key has a maximum lifetime of 90 days from creation. The expiresAt timestamp is set at creation time and cannot be extended. When a key expires, all requests using that key return 401 Unauthorized.

Activity Tracking

Flowstate records the lastUsedAt timestamp each time a key is used to authenticate a request. Monitor this field to identify unused keys that should be revoked.

Revocation

Keys can be revoked at any time from Settings > API Keys. When a key is revoked:

The revokedAt timestamp is recorded
Revocation is immediate -- all subsequent requests with that key return 401 Unauthorized
Revocation cannot be undone; you must create a new key if access is still needed

Revoking keys requires the SETTINGS_API_KEYS_DELETE permission.

Lifecycle States

State	`expiresAt`	`revokedAt`	Accepts Requests
Active	Future date	`null`	Yes
Expired	Past date	`null`	No
Revoked	Any	Set	No

Key Rotation

Rotate keys on a regular schedule to limit the blast radius of a compromised key. The recommended process ensures zero downtime:

Create a new key with the same permission scopes as the existing key
Update your integration to use the new key
Verify the integration works by confirming successful API calls
Revoke the old key once you have confirmed the new key is in use

WARNING

Always create the new key and update your integration before revoking the old key. If you revoke first, your integration will break until you configure the replacement.

Authentication

API keys are passed in the Authorization header using the Bearer scheme:

bash

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

The authentication middleware validates the key by:

Extracting the {identifier} segment for O(1) key lookup
Hashing the {secret} segment with SHA-256 and comparing against the stored hash
Checking that the key is not expired (expiresAt) or revoked (revokedAt)
Verifying the requested endpoint against the key's permission scopes

See the API Authentication guide for detailed usage examples and error response formats.

Managing Keys

Required Permissions

Action	Permission
View keys	`SETTINGS_API_KEYS_VIEW`
Create keys	`SETTINGS_API_KEYS_CREATE`
Revoke keys	`SETTINGS_API_KEYS_DELETE`

Viewing Keys

Navigate to Settings > API Keys to see all keys for your organization. The list shows:

Key name and description
Key prefix (e.g., private_k1a2b3c...) for identification
Permission scopes
Creation date and expiration date
Last used timestamp
Status (active, expired, or revoked)

Error Responses

HTTP Status	Code	Meaning
`401`	`UNAUTHORIZED`	Missing, invalid, expired, or revoked API key
`403`	`FORBIDDEN`	Valid key but insufficient permission scopes

json

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

json

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have the required scope: employees:write",
    "errorId": "err_def456"
  }
}

Security Best Practices

Store keys in a secrets manager -- Use environment variables or a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, Google Secret Manager, Azure Key Vault). Never hardcode keys in source code.
Use separate keys per integration -- If three systems connect to Flowstate, create three separate keys. This way you can revoke one without disrupting the others, and you get per-integration usage tracking.
Grant minimal permissions -- Only assign the scopes your integration actually needs. A read-only reporting tool should not have :write scopes.
Rotate every 30-60 days -- Do not wait for the 90-day expiration. Proactive rotation limits the window of exposure if a key is compromised.
Monitor usage via lastUsedAt -- Periodically review your keys in Settings > API Keys. If a key has not been used recently, consider whether it is still needed.
Never commit keys to source control -- Use .env files (excluded from version control) or CI/CD secrets. If a key is accidentally committed, revoke it immediately and rotate.
Restrict network access -- If your integration runs from known IP addresses, layer network-level controls (VPN, IP allowlisting) on top of API key authentication for defense in depth.

API Authentication -- API key format, request examples, and error handling
Roles & Permissions -- Role-based access control and permission model
Audit Logs -- API key creation, revocation, and usage events in the audit trail
SIEM Integration -- Stream API key events to your security monitoring platform

API Keys ​

Overview ​

Key Format ​

Creating API Keys ​

Permission Scopes ​

Key Lifecycle ​

Expiration ​

Activity Tracking ​

Revocation ​

Lifecycle States ​

Key Rotation ​

Authentication ​

Managing Keys ​

Required Permissions ​

Viewing Keys ​

Error Responses ​

Security Best Practices ​

Related Pages ​