Flow API: workspace, access and notifications
This article covers the methods that manage the workspace itself: its settings, members, invitations, roles and permissions, teams, service keys, and personal notification settings. For how roles and invitations work from the user's point of view, see Flow: members, roles, teams and billing.
All methods work in the workspace from X-Workspace-Id (or the workspace of a flw_… key) and check the caller's permissions. Permissions in the tables are written as resource.action, for example workspace.manage. General rules are in Flow API: basics.
Methods for a user session only
Some methods don't work within a single workspace but on behalf of a person across all of their workspaces. They're called by the Flow interface on sensever.com (a browser session or an embed token). API keys get 401 UNAUTHENTICATED: a key is issued for selected workspaces, while these methods by design cover all of a person's workspaces, or one that doesn't exist yet.
Method | Request | What it does |
|---|---|---|
Me and my workspaces |
| The user ( |
Create a workspace |
| A new workspace from a template; the creator becomes the owner |
Objects from all workspaces |
| "All workspaces" mode: one page of objects from all of the person's workspaces |
Approvals from all workspaces |
| Approvals assigned to the person across all workspaces; see Flow API: processes, approvals and external events |
Summary across all workspaces |
| Counts by status category, overdue, assignee, workspace and week; see Flow API: reports, SLA and business calendar |
Calendar and filters for all workspaces |
| "All objects" as a calendar, options for the "Type" and "Assignee" filters |
"By section" |
| The person's tasks from all workspaces in personal sections |
Calendar subscription |
| Secret iCalendar links to due dates |
| Daily digest and notification emails, one set of settings for all workspaces | |
My invitations |
| Workspace invitations addressed to the person |
Respond to an invitation |
|
|
The calendar, "By section", calendar subscriptions and email are described in Flow API: personal lists, calendar and email. The subscription document itself, GET /calendar-feeds/{token}, is public: the secret is in the URL.
For an integration, this means you know a key's list of workspaces when you issue it, and you read objects one workspace at a time — POST /objects/query with the right X-Workspace-Id. A key can't create a workspace or accept an invitation on a person's behalf.
is_system: true marks the person's primary workspace, Main: it can't be renamed or deleted (422 VALIDATION_FAILED, details.reason = system_workspace).
POST /workspaces
Field | Type | Description |
|---|---|---|
| string, required | Name, up to 200 characters |
| string | Template: |
| object or null | A template file instead of a system template, see "Template files" below. Only without |
| string or null | Full-text search language from |
| string or null | Language of the names the template creates: |
| string or null | The creator's IANA time zone (for example, |
{ "name": "Sales", "template": "crm", "locale": "en", "search_language": "english" }locale translates the names of types, fields and options, statuses and transitions, views, action buttons, rules, and the texts of their notifications. Keys (deal, won, amount, etc.), expressions and settings are the same in every language, so integrations work the same way with a workspace in any language. The Flow interface passes the creator's interface language. Without locale (or with null), the language comes from search_language (english → en, german → de, and so on), otherwise it's ru. Any other value, including en-US or EN, returns 422 VALIDATION_FAILED. Names are saved as workspace data: you can change them later, and changing the interface language doesn't rename them.
Response 201: workspace, the creator's principal_id (role owner) and template_result — which template steps were applied (applied) and which were skipped (skipped, with a reason). Ready-made template automations that need no setup are created enabled (the list is in Flow: automations); a rule with a webhook to an external system stays a disabled draft until a URL is set. One person can be a member of at most 50 workspaces. With an Idempotency-Key header, a repeated request returns the saved response and doesn't create a second workspace.
POST /me/objects/query
Reads objects from all of the person's active workspaces in one page. Body:
Field | Description |
|---|---|
|
|
|
|
| Only these workspaces (up to 100) |
| Status categories: |
|
|
| Only types with these keys, 1–50. The same key in different workspaces counts as one type; the options are |
| Case-insensitive title substring, up to 200 characters |
| Full-text search, up to 200 characters |
| Due date range on the type's |
Each response item is a compact summary: id, workspace (id, name, is_system), type, title, state, owner (principal_id, user_id, name, picture_url; user_id and name are null if you don't have workspace.read in that workspace), due, version, created_at, updated_at. A page reads at most 50 workspaces and has a time budget; workspaces that weren't read are listed in meta.skipped_workspaces, and meta.partial is true.
Workspace
Method | Request | Permission |
|---|---|---|
Read |
|
|
Rename, change quotas |
|
|
Delete |
|
|
The response contains id, name, plan, status (active, suspended, deleted), quotas, is_system, created_at, updated_at.
PATCH /workspace accepts name (up to 200 characters) and quotas — an object merged by key; null for a key restores the default value. Supported quotas: api_requests_per_minute, api_principal_requests_per_minute, queue.<queue|*>.weight, queue.<queue|*>.max_concurrency, queue.<queue|*>.rate_per_minute, indexed_multi_value_items, indexed_fields_per_type, indexed_fields_total, projection_rows.
DELETE /workspace requires confirmation with the exact name:
{ "name": "Sales department" }The response is {"deleted": true}. The workspace is marked as deleted and access is closed for all members and keys; further requests to it are rejected at authorization. The data isn't physically deleted.
Template files
A custom template is a file: you can download a type or a whole workspace, then create a type from the file in any workspace, or a new workspace. Templates aren't stored on the server, and there's no shared template list. In the interface, these are the "Download template" and "Upload template" buttons.
Method | Request | Permission |
|---|---|---|
Download a type or workspace as a file |
|
|
Create a type from a file |
|
|
New workspace from a file |
| user session only |
Presets for the "New type" form |
|
|
Create a type from a preset |
| same as creating from a file |
Download
GET /templates/file?kind=type&object_type=task returns one published type; GET /templates/file?kind=workspace returns all published types of the workspace. The file includes fields, the status process, restrictions, shared views, action buttons, automations, reminder rules, processes, relations between the file's types, and shared dashboards. The file contains no data: no objects, files, comments, members or personal views. References to specific people are replaced with roles or the object's assignee, and automations with call_webhook are left out.
{
"file": {"format": "sensever-flow-template", "version": 1, "kind": "type", "name": "Tasks", "definition": {}},
"skipped": [{"kind": "automation", "name": "Send to ERP", "object_type": "task", "reason": "webhook"}],
"skipped_total": 1
}skipped lists what didn't make it into the file (first 50), with a reason: webhook, instance_reference (a reference to a person, an object or a custom role), outside_template, unpublished, disabled. Save file as is — you don't need to parse definition. Errors: no object_type with kind=type — 422 with required; type not found — 404 NOT_FOUND; type not published — 422 with unpublished; no published types in the workspace — 422 with empty_workspace.
Create a type from a file
POST /templates/file/apply:
Field | Description |
|---|---|
| The |
| Singular and plural name of the main type, up to 200 characters; defaults to the names in the file |
| Key of the main type; must be free ( |
| IANA time zone for reminder rules; defaults to the zone of the workspace's working calendar |
Everything is created in one transaction: an error in any step rolls back the whole file. Taken keys of other types, relations and processes get a suffix _2, _3… Response 201: object_type (id, key, name, plural_name), object_types — all created types, and applied — the number of applied steps by kind. File errors return 422 VALIDATION_FAILED: invalid_file (not a Sensever Flow template file), wrong_kind (a workspace file — upload it when creating a workspace), invalid_definition; a definition larger than 256 KB returns 422 LIMIT_EXCEEDED.
POST /workspaces accepts a workspace file (and a type file too) in the template_file field: the new workspace gets the types and settings from the file with the file's names, untranslated; the request's timezone sets the zone for reminder rules.
Members
Method | Request | Permission |
|---|---|---|
List members |
|
|
Change roles or status |
|
|
Disable a member |
|
|
A member has principal_id, user_id, email, display_name, picture_url, role_keys (system roles), role_ids (all roles), team_ids, status (active, disabled, pending), created_at.
The name and photo come from the Sensever profile and are the same in every workspace: a rename or a new photo in the profile reaches Flow automatically. picture_url is an https URL of the photo, or null if there's no photo — in that case, draw initials.
PATCH accepts one of the two role fields, plus status:
Field | Description |
|---|---|
| Replaces system roles (up to 5); the member's custom roles stay |
| Replaces the whole set of roles, system and custom (up to 10 ids); an unknown id returns |
|
|
Rules:
changing the
ownerrole (or a role with theworkspace.deletepermission) and disabling an owner requireworkspace.delete;the last active owner can't lose the role or be disabled —
422 VALIDATION_FAILED;DELETEdoesn't remove a member but disables them: the record stays for history and auditing. Repeating it is safe;when a member is disabled, all their
flw_…keys are revoked and their webhook subscriptions are turned off.
You can't add a member directly: a person joins a workspace only by accepting an invitation.
Invitations
Method | Request | Permission |
|---|---|---|
Find a person in Sensever |
|
|
Open invitations |
|
|
Invite |
|
|
Cancel an invitation |
|
|
GET /workspace/people searches the Sensever people directory, not just Flow users: @name matches the beginning of a username; a name, email or phone number matches only exactly (a phone number only if the person has verified it and not hidden it). A query shorter than 2 characters finds nothing. The response contains accounts_id, name, username, picture_url, match (what matched) and state: member — already a member, invited — already invited, null — neither. Email and phone are not returned.
An invitation:
{ "accounts_id": "12345", "role_keys": ["member"] }or by email:
{ "email": "anna@example.com", "role_keys": ["viewer"] }role_keysare system roles, up to 5, default["member"]. A custom role is assigned after acceptance viaPATCH /workspace/members/{principal_id}withrole_ids.An email that belongs to a Sensever account invites that person. For any other email, Sensever Accounts sends a message, and the invitation waits until a person with that verified email accepts it. The
letterfield shows what happened to the email:sent,registered,limited,failed.Nothing is created in the workspace until the invitation is accepted.
Inviting the same person or email again returns the open invitation unchanged with code
200; a new one returns201.422 VALIDATION_FAILEDreasons:target_required,invalid_email,user_not_found,already_member,unknown_role.
You can cancel only an invitation that hasn't been answered; an answered one returns 422.
Roles and permissions
Method | Request | Permission |
|---|---|---|
Roles with permissions |
|
|
One role |
|
|
Create a custom role |
|
|
Rename a custom role |
|
|
Delete a custom role |
|
|
Replace role permissions |
|
|
A role has id, key (the system role key, or null for a custom role), name, system, member_count, permissions[], created_at. The list is ordered as follows: the system roles owner, admin, member, viewer, integration, then custom roles by name.
Permission row
Field | Description |
|---|---|
|
|
|
|
|
|
| The type the row applies to; |
| Required for |
| Required for |
| Only for |
System role permissions in a new workspace (templates may add to them):
Permission | owner | admin | member | viewer | integration |
|---|---|---|---|---|---|
| all | all | all | all | all |
| all | all | all | — | all |
| all | all | team | — | all |
| all | all | own | — | all |
| all | all | team | — | all |
| all | all | team | — | all |
| all | all | all | all | all |
| all | all | — | — | — |
| all | all | all | all | all |
| all | all | all | — | all |
| all | all | — | — | — |
| all | all | all | all | all |
| all | all | — | — | — |
| all | all | all | all | all |
| all | all | own | — | — |
| all | all | — | — | all |
| all | all | all | all | all |
| all | all | — | — | — |
| all | — | — | — | — |
What you can change
Custom roles — everything: the name (1–80 characters, unique case-insensitively), permissions, deletion.
POST /workspace/rolesacceptsnameandcopy_from— the id of a role whose permissions to copy (a system role works too).System roles can't be renamed or deleted (
422,system_role_readonly). The permissions ofadmin,memberandviewercan be changed; those ofownerandintegrationcan't.PUT /workspace/roles/{id}/permissionsatomically replaces the whole set of rows:{"permissions": [ … ]}, up to 2000 rows. A matching row keeps its id. Errors point topermissions[i]orpermissions[i].<field>:unknown_object_type,unknown_field,field_not_in_object_type,duplicate,too_many.Only someone who has the
workspace.deletepermission can grant, copy or remove it.A role that is someone's only role can't be deleted:
422within_use,details.principal_countanddetails.principal_ids(up to 100).
Role POST and PATCH and PUT …/permissions support Prefer: return=minimal: the response is then a compact DefinitionResult, and the full role is available at GET /workspace/roles/{id}.
Example: a "Managers" role — a copy of member that is allowed to change all objects of the deal type:
curl -s https://flow.sensever.com/v1/workspace/roles \
-H "Authorization: Bearer $FLOW_KEY" -H "X-Workspace-Id: $FLOW_WS" \
-H "Content-Type: application/json" \
-d '{ "name": "Managers", "copy_from": "<member role id>" }'Then read its permissions (GET /workspace/roles/{id}), add the row {"resource": "object", "action": "update", "scope": "all", "object_type_id": "<deal type id>"} and send the whole set to PUT /workspace/roles/{id}/permissions.
Permissions only allow
There are no denying rows: the effective permission is the broadest of all matching rows across all of the member's roles. A row with object_type_id: null applies to all types, and a row for a single type can't narrow it. So a role that works with only one type is built like this: it has no object, transition or object_action rows without a type, only rows for the type it needs.
Example: a purchasing department role sees and changes only objects of the purchase type. Create the role as a copy of member (so it keeps the schema.read, view.read, workspace.read rows and other basic workspace permissions), remove the object.*, transition.execute and object_action.execute rows with object_type_id: null from the set, and add rows for the type:
{
"permissions": [
{"resource": "object", "action": "read", "scope": "all", "object_type_id": "<purchase type id>"},
{"resource": "object", "action": "create", "scope": "all", "object_type_id": "<purchase type id>"},
{"resource": "object", "action": "update", "scope": "all", "object_type_id": "<purchase type id>"},
{"resource": "transition", "action": "execute", "scope": "all", "object_type_id": "<purchase type id>", "transition_key": "*"},
{"resource": "object", "action": "archive", "scope": "own", "object_type_id": "<purchase type id>"}
]
}Only the object rows are shown here; PUT replaces the whole set, so send them together with the role's other rows. Then assign the role to staff via PATCH /workspace/members/{principal_id} with role_ids, replacing the system role: if a person keeps member or viewer, they'll still see all types. When it's better to set up a separate workspace for the department is explained in Flow: members, roles, teams and billing.
Teams
A team is a group of members. It defines the team scope in permissions: "your team's objects".
Method | Request | Permission |
|---|---|---|
List teams |
|
|
Create |
|
|
Rename |
|
|
Delete |
|
|
Replace members |
|
|
A team has id, name, member_ids (principal ids of members), created_at. The name is 1–80 characters, unique case-insensitively. A team can include up to 1000 of the workspace's human members (active or disabled); an id from elsewhere returns 422 with unknown_member. Roles aren't assigned to teams: they're granted to members.
Workspace keys
Besides platform keys from the Sensever profile, a workspace has service keys flw_<prefix>_<secret>. They're useful when an integration should act as a service member or with narrow permissions.
Method | Request | Permission |
|---|---|---|
List keys (without secrets) |
|
|
Issue a key |
|
|
Revoke a key |
|
|
Issue body:
Field | Description |
|---|---|
| On whose behalf the key acts; defaults to the caller |
| Key scopes, up to 50; empty means all of the member's permissions |
| An expiry in the future; |
Response 201 contains secret — the full key for Authorization: Bearer. It's shown once; a repeat with the same Idempotency-Key returns secret: null. The list shows key_prefix, scopes, expires_at, last_used_at (updated at most once a minute) and revoked_at. A revoked key gets 401 immediately.
Key scopes
The format is <resource>:<action> or <resource>:*:
Resource | Actions |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Any action on a resource includes its
read;object:<action>coversfield:<action>;object:archivecoversrestore.A key is never broader than its member: both scopes and roles apply. A scope denial returns
403withdetails.reason = key_scope.An unknown scope returns
422withunknown_scope.objects:readandobject.readare accepted and saved asobject:read.A key with scopes can only issue keys no broader than itself, and can manage webhooks only if it has
object:read.
For example, a key for ingesting events from an external system: ["integration:ingest_events"]; a read-only key for tasks: ["object:read"].
My notifications
A person's personal notification settings in the current workspace. Any valid key can read and change them — it changes the settings of its owner.
Method | Request |
|---|---|
Read |
|
Change |
|
Field | Description |
|---|---|
|
|
| Automation notifications |
| Due date reminders |
| Everything from processes: approvals, escalations, step notifications |
| Mentions: someone named you with @ in a text field of an object you can read (for example, in the description) |
| A message in the conversation with "Sensever Flow"; when off, no message arrives in chat |
| Push for that message; when off, the message arrives silently |
| Notification emails from this workspace; off by default |
| Which categories also arrive by email when |
|
|
| Ids of automations whose notifications are off (up to 500) |
| Ids of reminder rules that are off (up to 500) |
| Read-only: what can notify the person here ( |
If both chat and email are off for a category, notifications in that category aren't delivered at all. An email isn't sent right away: one email collects everything that arrived during the wait, at most once every 15 minutes and not before quiet hours end. Notification emails in general, the daily digest, and the email time zone and language are personal settings for all workspaces: GET and PATCH /me/mail-settings, user session only (see Flow API: personal lists, calendar and email).
PATCH is a partial update: categories, channels and email_categories are merged by key, while quiet_hours and the lists of muted sources are replaced entirely. Error codes in details.fields[].code: required, unknown_property, invalid_value, invalid_time, invalid_timezone, unknown_automation, unknown_reminder_rule.
curl -s -X PATCH https://flow.sensever.com/v1/workspace/notification-settings \
-H "Authorization: Bearer $FLOW_KEY" -H "X-Workspace-Id: $FLOW_WS" \
-H "Content-Type: application/json" \
-d '{ "categories": { "reminders": false }, "channels": { "email": true }, "email_categories": { "mentions": true }, "quiet_hours": { "from": "21:00", "to": "09:00", "timezone": "Europe/Moscow" } }'Who gets notifications and when is described in Flow: notifications and reminders.
Search language
Method | Request | Permission |
|---|---|---|
Read |
| any member |
Change |
|
|
The response contains language (the current language of the full-text index) and languages (the supported ones). The default is simple: no word-form handling, words match by prefix. After a language change, the response contains reindex: true: objects are reindexed in the background, and until that finishes, search finds only objects already reindexed. How to search is covered in Flow API: query language and search.
ความคิดเห็น