Skip to main content
Every /api/v1 request is authenticated with an API key sent as a Bearer token.
Keys start with 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.
The page lists each key’s Name (with when it was last used), Key prefix, Access, Workspaces (default first), Issued by and Status (Active, Expired or Revoked, with the expiry or revocation date).
A key carries the full API access of the role chosen when it was created, and a key that acts for members can act as any of them. Store it in a secrets manager, never in client-side code or a repository, and revoke it the moment it is no longer needed.

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 the X-Act-As header, as key=value, and the workspace with the X-Workspace-Id header:
Both headers are required on every call. The member can only be named with the header, never in the request body, and the key has no default workspace: a call without 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.
Set Limit access to to a role. With Each member’s own access, a call that names an owner gets every permission except managing members and API keys, though it still cannot do what only an owner can.

Workspaces

A key belongs to the organisation and covers the workspaces chosen when it was created. On an ordinary key, a request with no X-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.