/api/v1 request is authenticated with an API key sent as a Bearer token.
fsk_. Flowsign stores only a hash of the key; the full value is shown once, when the key is created.
Creating and managing keys
Keys are created in the app at Settings > API keys (my.flowsign.app/settings/api-keys). An owner can create, list and revoke any key. A member whose role has the Manage API keys permission can do the same for ordinary keys, within two limits: the key’s role must not exceed their own, and every workspace on the key must be one where their role has the permission. Keys outside those limits do not appear in their list. Keys cannot be created or revoked through the API itself.- Name the key after where it will live (for example “Production server”).
- Act for members (owners only) makes a key that runs each call as a member you name, instead of as a role. Limit access to then caps what it can do: Each member’s own access, or a role. See Keys that act for members.
- Role is what an ordinary key can do. The key acts with that role’s permissions, not the issuer’s, and only roles with the API access permission are offered.
- Workspaces are where the key acts. Choose one or more; the first is the default when a call on an ordinary key names no workspace. The list is fixed for the key’s whole life.
- Expiry is optional. A key with no expiry works until you revoke it; a key with an expiry stops working at the end of that day, in the local time of whoever created it.
- The key value is displayed once in a reveal dialog and cannot be read again. If you lose it, create a new key.
- Revoke a key from the same page. Revocation is immediate and permanent.
- A key cannot be edited, and there is no rotate operation. To change or rotate one, create a new key, move your integration to it, then revoke the old one.
- An organisation can hold at most 50 unrevoked keys, and expired keys count until they are revoked. Creating one beyond that returns
409; revoke a key to make room.
Who can use the API
- Creating keys requires an owner, or a role with the Manage API keys permission. Only an owner can create or revoke a key that acts for members.
- Permission. The role a key is given must have the API access permission. The built-in Admin role has it; Sender and Viewer do not. Built-in roles can’t be edited, so to give it to another role an owner clones or creates one on Roles & Permissions and turns it on there.
- Acting as a role. An ordinary key acts with the permissions of the role chosen at creation, not the issuer’s, and it is never an owner. Its work is attributed to the user who issued it. Visibility is the exception, because it follows the issuer. Without the view all packages permission (
canViewAllPackages), a key sees only the packages its issuer owns or has been shared, including the ones the key created. Templates follow the issuer whatever the role: a key sees only the templates its issuer created or has been shared. Endpoints that change data check that role’s permissions, so a key on a role without the send permission cannot send packages (403 Missing permission: canSendPackages). Audit events record the issuing user alongside the key. To use a colleague’s template through a key, share it with the key’s issuer. The role’s template access decides whether the key can use the templates it sees (USE) or also create and edit them (CREATE). - Acting as a member. A key that acts for members has no identity of its own: every call names a member and runs with that member’s permissions. Audit events name the member the call acted for, are marked as made through the API, and record the key. See Keys that act for members.
- Webhook endpoints (
/api/v1/webhooks) need the manage webhooks permission on the key’s role. - Plan. The public API is included in the Enterprise plan. Webhooks are a separate feature on the same plan. Calls from organisations without the feature return
402. - IP allowlist. If your organisation has an IP allowlist (Settings > Security), API calls from other addresses are refused with
403 IP address not allowed. A request whose client address cannot be determined is refused the same way.
Keys that act for members
An ordinary key suits a system that sends on the organisation’s behalf. A key that acts for members suits a system your team already works in, such as an HR platform: each call runs as the person who triggered it. Packages are sent in their name, replies and notifications reach them, and the package sits in their list. Every call on such a key names the member with theX-Act-As header, as key=value, and the workspace with the X-Workspace-Id header:
X-Workspace-Id is refused with 400.
The key on the left of the = is one of:
Keys are lowercase and are not case sensitive:
Employee_ID=E-1001 matches employee_id.
What the call can do:
- The member’s own permissions in the workspace the call acts in, capped by the Limit access to role when the key has one.
- Never member management or API key management, whoever is named.
- API access comes from the key. The member’s role does not need the API access permission. A Limit access to role must have it, and if that role later loses it the key stops working with
401. - Only active members of that workspace. A value that matches nobody, a deactivated member, or a member who does not belong to the workspace the call acts in is refused with
403. The call never falls back to the key’s issuer. - Only the templates the member can see. Template sharing applies, so the call lists and uses the templates the named member can see, not every template in the workspace.
- Edit locks as that member. A package or template the named member has open for editing in the app does not block the call. One that another member is editing returns
409, as it does for any key.
Workspaces
A key belongs to the organisation and covers the workspaces chosen when it was created. On an ordinary key, a request with noX-Workspace-Id acts in the key’s default workspace, the first one chosen. Send X-Workspace-Id to act in any other workspace on the key; an id outside the key’s list is refused with 401. A key that acts for members has no default workspace and must send X-Workspace-Id on every call. See Workspaces.
Why a request is refused
See Errors for the response format, validation details and rate limits.

