foliot docs

Guides / Workspaces and members

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.

Note: 

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}/role with 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}/invitations with 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, with 400.
  • 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 429 and 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.cancelled and invitation.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 403 as it is not a member. A person who is not a member gets 404.
  • 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}/limits as any member of the workspace. A person who is not a member gets 404.
  • Read limits from GET /me with 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/workspaces creates the workspace and makes you its owner. The slug is 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 409 status 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 /me tells you if you can. canCreateWorkspace is true while 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 403 because 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 404 status code.
  • Its owners still see it. GET /me lists a closed workspace to its owners only, with closedAt and purgeAfter. 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 purgeAfter has 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.restored and workspace.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.
    • 400 if confirmName is not the workspace’s name (spaces around it are ignored, but case is not) or the reason is shorter than 8 characters.
    • 404 to close a workspace that is already closed (a closed workspace answers 404 on every route except restore and purge).
    • 409 to 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:

  1. its longest-standing admin, or
  2. if it has no admins, its longest-standing operator, or
  3. 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.