shiftlabs Start free
Menu Workspace and roles

Workspace and roles

A workspace holds your workflows, their runs and everything they use. Members and API keys act in it with one of three roles.

What a workspace holds

Everything you deploy and run belongs to one workspace. Every /v1 call acts on the workspace of the API key or session that makes it. Another workspace's run or trigger answers 404.

  • Workflows and runs

    Workflows with their versions, triggers, schedules and releases, and the runs they start. See Runs and steps and Projects.

  • Credentials and settings

    Secrets, connections and vars, with each workflow's overrides and links.

  • People and keys

    Members, API keys and the audit log, which admins read.

  • Plan and limits

    The workspace's plan and the limits that come with it. GET /v1/me returns them with the workspace. See Limits.

  • After you sign up, you create your workspace and become its first admin. You can create up to 5 workspaces and switch between them from the workspace menu. See Workspaces.
  • You give it a name and an id. The name is 1 to 64 characters, and an admin can rename it on the Workspace screen or with PATCH /v1/workspace.
  • The id is 1 to 63 lowercase letters, digits or hyphens, starting with a letter or digit, and stays the same after a rename. Another workspace's id is refused.

Roles

Every member and every API key has one role: viewer, developer or admin, from least to most. Each role can do everything the roles below it can.

  • viewer

    Reads workflows, runs, logs, vars, secret names and connections. Trigger URLs stay hidden.

  • developer

    Deploys, runs, re-runs, cancels and pauses workflows, manages triggers, and sets vars and a workflow's connections.

  • admin

    Also sets secrets and connections, terminates runs, manages members, API keys, billing and alerts, and reads the audit log.

Each route needs one capability, and each role holds a set of them. A caller without the route's capability gets 403 with the role it needs. GET /v1/me lists the caller's role and capabilities. See Roles for every capability.

Members and invitations

Admins invite people by email, each with a role, from Invite on the Workspace screen or with POST /v1/members/invitations {"email", "role"}. The invitation is sent by email, and the answer gives its expires_at.

  • Members are listed with their role and status, active or pending, on the Workspace screen and at GET /v1/members. Only admins see the list.
  • An admin changes a member's role with PATCH /v1/members/:id {"role"}. The member's next request uses the new role.
  • Removing a member with DELETE /v1/members/:id also ends their sessions in this workspace.
  • The last active admin can't be demoted or removed: 409. Keep a second admin.
  • Invitations per 24 hours depend on the plan. See Limits.
  • An admin can end a member's dashboard sessions without removing them. See Sessions.

API keys

An API key belongs to one workspace and has one role. Admins create and revoke keys, and a key is shown only once.

  • capabilities narrows a key to part of what its role allows, such as ["workflow.deploy"] for CI. scope limits it to named workflows or agents.
  • A key never reaches further than the person or key that created it.
  • A key lasts 1 to 365 days, 90 by default. A workspace holds at most 20 active keys.
  • See API keys for the full rules.

Reference

  • Roles

    Every capability and the role that holds it.

  • API keys

    Creating, narrowing, scoping and revoking keys.

  • Sessions

    How long a dashboard session lasts, and how to end one.

  • Plans and billing

    Free and Pro, and who manages billing.