Create and manage API keys

An API key lets another system, such as a nightly HR export or a data warehouse job, read or change data through Flowstate’s REST API. Each key has its own permissions and expires on a date you choose.

You need to be a Flowstate admin. A key can only have permissions your own role includes.

Create a key

1. Go to Settings → Users & Access → API Keys and select Create API Key.
2. Enter a Name that says which system uses it, such as “Nightly HR sync”.
3. Choose an Expiration: 7 days, 30 days, 60 days or 90 days.
4. Under Permissions, tick only what the system needs.
5. Create the key and copy it straight away. It’s only shown once.

Done when: the key is listed as Active.

Replace a key before it expires

Keys can’t be extended or edited.

1. Create a new key with the same permissions.
2. Update the system to use the new key.
3. Check the new key’s last-used time changes.
4. Revoke the old key from its row.

Revoke a key

Revoke the key from its row. It stops working straight away and can’t be restored.

Good practice

• One key per system, so you can revoke one without breaking the others.
• Keep keys in a secrets manager, never in code or a shared document.
• Review the list regularly. Revoke keys marked Never used or not used for a while.

If something’s not right

“Cannot grant permissions you do not have”. You ticked a permission your role doesn’t include. Untick it, or ask someone whose role includes it.

A system suddenly gets 401 errors. The key has expired or been revoked. Create a new one.

A system gets permission errors on some requests. The key is missing a permission. Create a new key with the right permissions, switch the system over, then revoke the old one.

For your technical team

Keys start with private_. Send them as Authorization: Bearer private_…. Examples and error formats: API authentication.