Workspaces and roles
How workspaces separate files, people, and billing, what each member role can do, and how API keys and S3 app keys fit alongside signed-in users.
On this page
A workspace is the boundary for everything in SteadyLink: buckets and files, members, API keys, usage, billing, and settings. This page is for workspace owners and admins deciding who gets which role, and for developers deciding which credential an integration should use.
Workspaces#
When you sign up, you get a workspace and you are its owner. You can create more workspaces and be invited to other people's. Nothing is shared between workspaces: a file, a key, or a member in one workspace has no access to another.
Each workspace has:
- Buckets and files, and the usage they generate.
- Members, each with one role.
- API keys, each bound to this workspace only.
- A plan, which sets storage, delivery, seats, and API limits.
- Defaults for new files: whether new files start public or private, and whether delivery requires a clean malware scan. Change them in Settings > Workspace.
Roles#
Every member has exactly one role. Roles are a fixed set of permissions:
| Permission | Viewer | Member | Admin | Owner |
|---|---|---|---|---|
See workspace details and members (workspace:read) | Yes | Yes | Yes | Yes |
See files, folders, and revisions (assets:read) | Yes | Yes | Yes | Yes |
See analytics (analytics:read) | Yes | Yes | Yes | Yes |
Upload, replace, move, share, and delete files (assets:write) | Yes | Yes | Yes | |
Run file conversions (conversions:run) | Yes | Yes | Yes | |
Change settings, members, invitations, API keys, and platform controls (workspace:admin) | Yes | Yes | ||
Manage billing (billing:manage) | Yes | Yes | ||
Usage overage policy, ownership transfer, workspace deletion (ownership:manage) | Yes |
A request your role does not allow returns 403 with the code insufficient_workspace_permission, the permission that was missing, and your role.
Rules for admins and owners#
- Admins can invite, change, and remove members and viewers. Only the owner can invite an admin, change an admin's role, or remove an admin.
- Every workspace has exactly one owner. The owner cannot be removed or demoted directly; transfer ownership to another member first. After a transfer, the previous owner becomes an admin.
- Only the owner can delete the workspace, and only from a signed-in session, by typing the workspace name to confirm.
Invitations#
Admins and owners invite people from Settings > Members > Invite member, choosing a role. An invitation expires after 7 days by default and can be set to anywhere from 1 to 30 days through the API. Inviting the same email again revokes the earlier pending invitation. Pending invitations count toward your plan's seat limit along with current members, so revoke invitations nobody will accept.
Three kinds of credential#
People sign in; integrations use keys. SteadyLink has three kinds of credential and each one answers "who is acting" differently.
| User session | Workspace API key | S3 app key | |
|---|---|---|---|
| Who it acts as | A person | The workspace, not a person | The person who created it |
| Created by | Signing in | An owner or admin in Dashboard > Developers | Any member, for themselves, from a signed-in session (viewers can create read-only keys only) |
| How it is sent | Authorization: Bearer ... | X-API-Key: slk_... | AWS Signature Version 4 |
| Permissions | The person's role | The key's scopes | The person's current role, optionally read-only and limited to one bucket |
| Workspaces | Every workspace the person belongs to | Exactly one | Exactly one |
| Used for | The dashboard | Servers, CI, the SDKs, the CLI, the GitHub Action | S3 tools such as rclone, restic, Cyberduck, the AWS CLI |
Send either a bearer token or an API key, never both. A request with both headers is rejected with 400.
Workspace API keys#
An API key belongs to the workspace. It keeps working when the person who created it leaves, and it can do only what its scopes allow:
| Scope | Allows |
|---|---|
assets:read | Reading buckets, files, revisions, upload status, and signed-link records |
assets:write | Uploads, replacements, revisions, visibility, signed links, and other file changes |
analytics:read | Traffic, storage, and activity analytics |
workspace:read | Workspace details and members |
workspace:admin | Platform controls such as delivery policy, webhooks, delivery domains, and SSO configuration |
Some actions always need a signed-in person, whatever scopes a key has: creating, listing, and revoking API keys; managing members and invitations; changing workspace settings; creating S3 app keys; and two-step verification. A key cannot create another key.
Each plan limits how many API keys can be active at once. See API key safety for scopes, expiry, and rotation.
S3 app keys#
An S3 app key lets S3-compatible tools reach your buckets. It acts as the person who made it, and SteadyLink re-checks that person's membership and role on every request. Remove the member, or lower them to viewer, and their write access through S3 stops immediately. A key can also be made read-only or limited to one bucket. Each person can have up to 20 active S3 app keys per workspace. See the S3-compatible API.
Choosing the workspace for a request#
An API key is bound to one workspace, so requests made with it need nothing more. If you also send X-Workspace-Id with a key, it must match the key's workspace or the request is refused with 403.
A user session can belong to several workspaces. Send the X-Workspace-Id header with the workspace ID to choose one:
curl https://api.steadylink.io/api/workspaces/current \
-H "Authorization: Bearer $STEADYLINK_ACCESS_TOKEN" \
-H "X-Workspace-Id: 9d1c7e40-2b6a-4f3e-8a15-6c0e2f9b4d71"If the person belongs to exactly one workspace, the header can be omitted. If they belong to more than one and the header is missing, the request returns 400 with the code workspace_required.
Single sign-on and roles#
On plans with single sign-on, a workspace can require members to sign in through its identity provider. People who sign in through SSO for the first time join the workspace as members. SSO enforcement applies to user sessions only; API keys and S3 app keys keep working. See Single sign-on.