Workspaces and members
This page explains how a workspace gets its owners and members and what happens when someone leaves, closes a workspace, or deletes their account.
Roles are managed in Foliot. Signing in tells Foliot who you are, not what you can do. A workspace’s owners and admins assign roles (see Managing members below). You join a workspace by creating it or accepting an invitation. You become the owner of the workspace(s) you create. For invited workspaces, your role is set by the owner/admin of that workspace.
A workspace’s owners
The person who creates a workspace is its first owner (see Creating your own workspace). Only owners can make someone else an owner, in one of two ways:
-
Make a member an owner. In Foliot Console, open Settings → Members and choose Owner as that member’s role. With the API, send
PUT /workspaces/{workspaceId}/members/{userId}/rolewith the following body:{ "role": "owner" } -
Invite someone as an owner. In Foliot Console, use the invite form on Settings → Members and choose Owner as the role. With the API, send
POST /workspaces/{workspaceId}/invitationswith this body:{ "email": "ada@example.com", "firstName": "Ada", "lastName": "Lovelace", "role": "owner" }They are added to the workspace the first time they sign in with that email address after verifying it (see How an invitation works).
You can find the ids of your own workspaces with GET /me.
Managing members
An owner or admin of a workspace decides what each member can do. The API key cannot be used to make membership changes. Only owners can manage other owners. Below are the list of related API calls:
| Call | What it does |
|---|---|
GET /workspaces/{workspaceId}/members |
Lists the members. Paged by limit and cursor. |
PUT /workspaces/{workspaceId}/members/{userId}/role |
Set a member’s role. |
DELETE /workspaces/{workspaceId}/members/{userId} |
Removes the member from the workspace. |
GET /workspaces/{workspaceId}/history |
See membership audit history. Paged by limit and cursor. |
POST /workspaces/{workspaceId}/invitations |
Invites a person by email, with their first and last name and a role. Responds with 201 with the invitation details. See below. |
GET /workspaces/{workspaceId}/invitations |
Lists the pending invitations, with the invited addresses. Paged by limit and cursor. |
DELETE /workspaces/{workspaceId}/invitations/{invitationId} |
Cancels a pending invitation, so the person will not join this workspace. Their sign-up link keeps working only if another workspace has also invited the address, and then only for that workspace. |
How an invitation works
- A person without an account gets an email inviting them to sign up. Once they complete their sign up and verify that address, they become members of a workspace with the role assigned at invite time.
- A person who already has an account gets an invitation email from Foliot and is added to the new workspace when they next open Foliot Console.
- Use an address written in plain Latin characters. Foliot refuses an address that has an accented or non-Latin character, such as
josé@example.com, with400. - Sending is limited. A workspace can send only so many invitations per hour and only a few to the same address per day, including cancelled ones. Going over this limit returns
429and nothing is sent. - If the email service is unavailable the call answers
503. Try again: the same invitation is never emailed twice. - Cancelling means the person will not join your workspace. If they have no account yet, the sign-up link in their email also stops working, unless another workspace has invited the same address. In that case the link still lets them sign up and join that workspace, but not yours.
- Closing the workspace pauses its pending invitations. Restoring it brings back the ones that have not expired (see Closing a workspace).
- The history records
invitation.sent,invitation.cancelledandinvitation.accepted, naming the invitation by the first and last name you gave, but never the invited address.
Other rules about members
- People can join someone else’s workspace only by invitation. Changing the role of someone who is not a member returns
404. - A workspace’s only owner cannot be demoted or removed, even by themselves: the call answers
409. Make someone else an owner first. - Removing someone keeps their account. They can still sign in and create workspaces of their own (see below). To let them back into your workspace, invite them again.
- Role changes and removals are kept in the workspace history, with who made them.
Leaving a workspace
Any member, regardless of their role, can leave a workspace without requiring an approval. Use Leave workspace under Settings in Foliot Console or call POST /workspaces/{workspaceId}/leave with your own session (204).
- It takes effect at once. They lose access to the workspace and its apps starting on their next request. Any bulk action they started stops before its next run. Their account and any other workspace they belong to is untouched.
- The owners and admins are notified. Each owner and admin receives an email notification about the person who left, unless Foliot does not have their email address yet. The departure is also recorded in the workspace’s history.
- The only owner cannot leave (
409). They have to make another member an owner first or close the workspace. - It is for a person. An app’s API key gets
403as it is not a member. A person who is not a member gets404. - To come back, a user needs to be reinvited by an owner or admin.
Membership limits
Your plan determines how many members and apps your workspace can have. Pending invitations count as members, and deleted apps do not count. At the limit, Foliot refuses a new invitation, a new app, or restoring a deleted app, with 402 and the error code usage_limit. Lowering a limit does not remove members or apps - only the next one is refused, and an invitation already sent can still be accepted.
Platform limits
Every workspace is held to four platform limits. Each has Foliot’s default value, and a workspace can be given its own value instead.
| Limit | What it covers |
|---|---|
| Payload size | The most a run’s input, a step’s output, a signal’s payload, or one entry of a state edit can hold, measured as compact JSON. |
| Answer time for a pushed task | How long Foliot waits for your handler to answer a pushed task in the same request. A step’s own timeout can make it shorter, and the task’s respondBy tells your handler when it ends. |
| History kept after a run finishes | How long a finished run keeps its full history before Foliot reduces it to a summary. |
| Signal keep time | How long a signal waits for a step to take it. |
A limit can change at once or at a set time. Each call is held to the limits in effect at the moment it is made, even when the call belongs to a run that started before the change. The two time limits are fixed earlier: a run keeps the history time in effect when it finished, and a signal keeps the keep time in effect when it arrived. So lowering either one never shortens a run that has already finished or a signal that is already waiting.
You can see your workspace’s limits in three places:
- Open Settings → Limits in Foliot Console to see each value, whether it is Foliot’s default or set for your workspace, since when it applies, and any change that is scheduled.
- Call
GET /workspaces/{workspaceId}/limitsas any member of the workspace. A person who is not a member gets404. - Read
limitsfromGET /mewith your app’s API key, so your service can size its payloads and its answers without a person’s session. An app’s key cannot call the workspace endpoint above.
A finished run also says when its full history will be reduced to a summary: retainUntil on the run, and Full history until on the run’s page in Foliot Console.
Creating your own workspace
Anyone signed in can create a workspace, and becomes its owner at once.
-
In Foliot Console, a person who does not belong to a workspace sees a “Create your workspace” form in place of every page, and anyone with an existing workspace can create another one using New workspace in the account menu.
-
Through the API,
POST /me/workspacescreates the workspace and makes you its owner. Theslugis optional: Foliot creates a slug based on the name if you leave it out.{ "name": "Acme Payments", "slug": "acme-payments" } -
You can create a limited number. Only workspaces you created count until they are purged. Leaving one or handing it to another owner does not free a slot; closing it and having it purged does. Workspaces created by someone else do not count, even if you currently own them. At the limit, trying to create another gets a
409status code (“you have reached the maximum number of allowed workspaces”). You can still be made an owner of other workspaces. -
Other workspaces don’t matter. You can create one whether you belong to other workspaces or not.
-
GET /metells you if you can.canCreateWorkspaceistruewhile you are under the limit, and only then does Foliot Console show New workspace. -
Invitations still work. If you were invited somewhere and create your own workspace first, you still join the one that invited you.
-
Only people can create workspaces. An app’s API key gets
403because it is not a member of anything and cannot own the workspace. -
A slug already in use gets
409(when you leave the slug out, it is made from the name).
Closing a workspace
An owner can close a workspace that is no longer needed. Closing can be undone for a limited period. After that, the workspace is purged completely. These calls need an owner’s own session and nothing else: a member who is not an owner or an app’s API key are both refused.
You can close a workspace from Settings, Workspace, and then by giving a reason and typing its name to confirm closure. You can also use the following API endpoints:
| Call | What it does |
|---|---|
POST /workspaces/{workspaceId}/close |
Closes the workspace (body { "reason": "...", "confirmName": "..." }). The reason is required and recorded. confirmName is the workspace’s name, typed out. |
POST /workspaces/{workspaceId}/restore |
Reopens a closed workspace before its purgeAfter. |
POST /workspaces/{workspaceId}/purge |
Purges a closed workspace now instead of at purgeAfter (body { "confirmName": "..." }). Answers 202: the purge runs in the background within a few minutes. |
- Closing takes effect immediately. Every app in the workspace stops their runs. Pending invitations are suspended. Every member loses access, owners included: on every route, the workspace and its apps return
404status code. - Its owners still see it.
GET /melists a closed workspace to its owners only, withclosedAtandpurgeAfter. To every other member it is gone. Foliot Console shows it in the account menu under “Closed workspaces”, with Restore and Purge now. - Restoring brings back the workspace, its members’ access, and the apps the closure stopped, with their existing API keys and signing secrets. An app deleted on its own before the closure stays deleted. Its time to be restored keeps running while the workspace is closed. If that time has run out by the time the workspace is restored, the app is permanently deleted shortly after. Bulk jobs the closure cancelled stay cancelled, so submit them again. Invitations that have not expired can be accepted again.
- Purging removes the workspace and everything within it: its apps with their workflows, runs and history, its members, invitations and history. It cannot be undone. Once a purge has been requested or
purgeAfterhas passed, the workspace can no longer be restored (409). - The workspace’s slug is kept while it is closed so no one else can claim it. It becomes usable again once the workspace has been purged.
- The history records
workspace.closed,workspace.restoredandworkspace.purge_requested, with who did each. The closure’s reason is also recorded on each app it stopped, in that app’s credential history. - Refusals.
400ifconfirmNameis not the workspace’s name (spaces around it are ignored, but case is not) or the reason is shorter than 8 characters.404to close a workspace that is already closed (a closed workspace answers404on every route except restore and purge).409to restore one that is not closed or whose purge is due, and to purge one that is not closed.
A workspace with no owner
When the last owner’s account is deleted, their access is removed. Unlike leaving, this cannot be refused, because the account is already gone. In the same step, Foliot makes someone else the workspace’s owner:
- its longest-standing admin, or
- if it has no admins, its longest-standing operator, or
- if it has neither, its longest-standing viewer.
Standing is determined based on when they joined the workspace. Two people who joined at the same time are ordered by their user id, so the same workspace always gets the same answer. The workspace’s history records it as member.auto_promoted, with an actorKind of system, and Foliot emails the new owner to say why. The new owner can then assign other owners to the workspace.
A closed workspace is the exception. Nobody is made its owner and it stays closed until it is purged.
An open workspace is left without an owner only when the last owner’s account is deleted and nobody else is in it, so there is no one to make owner. The workspace, its apps and their runs carry on, but nothing that needs an owner or admin can be done (revealing or rotating secrets, updating an app, managing members and invitations). Keeping two owners avoids this. To recover such a workspace, contact Foliot support.