Workspaces and roles

A workspace holds a set of apps, the people who work on them, a plan and an audit log. Each person in it has a workspace role, and each app has its own list of people with app roles. This page explains both kinds of role and how they combine.

Workspaces

Every app belongs to one workspace, and its name starts with the workspace’s slug: acme/hello is the app hello in the workspace acme. The slug is also in the app’s address, https://hello--acme.jiayang-apps.cloud.

A workspace also has:

Members, each with a workspace role: member, admin or owner.
A plan, which sets how many apps and members it can have. See Plans and billing.
An audit log of every request to its apps and every change made to it. See Audit log.
Optionally, a list of email domains that members and sharing are limited to.

Signing up doesn’t make a workspace. You create one, or someone adds you to theirs.

Create a workspace

jiayang workspace create acme

Created workspace acme. You own it.

The slug is lowercase letters, digits and single dashes, up to 30 characters, and it can’t change later. The dashboard calls it the short name. --name sets a display name, which defaults to the slug. You can also create a workspace in the dashboard.

A new workspace is on the Free plan. One account can own up to 50 workspaces. Workspaces you’re a member of but don’t own don’t count.

What can go wrong:

error: That short name is taken, by another workspace or by one deleted in the last 30 days. Pick another.

A deleted workspace keeps its slug for 30 days, so you can’t make it again straight away under the same one.

error: Workspace slugs are lowercase letters, digits and single dashes, up to 30.

See your workspaces

jiayang workspace list

acme                           owner   free      acme

The columns are the slug, your role, the plan and the display name.

jiayang workspace show acme

acme (acme)
your role: owner
plan: free
allowed email domains: any
container apps: none on this plan

jiayang workspace members acme

owner   ada@example.com
admin   bob@example.com
member  grace@example.com

Workspace roles

	member	admin	owner
Open apps shared with them, or open to the whole workspace	Yes	Yes	Yes
Create apps, and own the ones they create	Yes	Yes	Yes
See the workspace’s members	Yes	Yes	Yes
Manage every app: deploy, configure, share and delete	No	Yes	Yes
Add and remove members and admins	No	Yes	Yes
Read the audit log and the workspace’s usage	No	Yes	Yes
Rename the workspace and set its allowed email domains	No	Yes	Yes
See the workspace’s billing	No	Yes	Yes
Add and remove owners	No	No	Yes
Change the plan	No	No	Yes
Export the workspace, or an app’s database	No	No	Yes
Delete the workspace	No	No	Yes

An owner deletes a workspace in the dashboard, under the workspace’s Settings, then Danger zone. The CLI can’t: a CLI session is never enough to delete a workspace.

A workspace always has at least one owner. Adding and removing people is on Members and invitations. In short:

jiayang workspace add acme grace@example.com

grace@example.com is a member of acme.

--role admin or --role owner adds someone with that role, or changes the role of someone already in the workspace. Only an owner can make someone an owner, or change or remove an owner. An admin who tries gets:

error: You don't have permission to do that.

App roles

Each app keeps its own list of people and their roles on it. The person who creates an app becomes its owner.

	viewer	editor	owner
Open and use the app	Yes	Yes	Yes
See the app’s versions	No	Yes	Yes
Deploy, roll back and rename it	No	Yes	Yes
Manage its environment variables, secrets and bypass tokens	No	Yes	Yes
Share it, and change its visibility	No	No	Yes
Open public paths on it and set their verifiers, in the dashboard	No	No	Yes
Delete it	No	No	Yes
Has to be a member of the workspace	No	Yes	Yes

You give someone an app role by sharing the app with them:

jiayang share acme/hello grace@example.com --role editor

A viewer can be anyone with an email address. Editors and owners work on the app through the workspace, so they have to be members first:

error: Editors and owners must be members of the workspace. Add them first.

An app always has at least one owner. Taking the role from the last one fails with An app needs at least one owner. See Share an app for more on sharing.

The role also reaches your app: it’s the role claim in the identity token, so your code can let editors do more than viewers. The SDK overview shows how to check it.

Visibility

An app is either private or open to the whole workspace:

private, the default: only the people it’s shared with can open it.
workspace: every member of the workspace can open it as a viewer, as well as the people it’s shared with.

jiayang app visibility acme/hello workspace

Everyone in acme can view acme/hello.

jiayang app visibility acme/hello private

acme/hello is private: only people it's shared with.

Changing visibility counts as sharing, so it takes an app owner, or a workspace owner or admin. You can also set it with jiayang deploy --create --visibility workspace when the deploy makes the app.

Delete an app

jiayang app delete acme/hello --yes

Deleted acme/hello.

Without --yes, nothing is deleted:

error: this deletes acme/hello, its data and its tokens. Run again with --yes

The app’s versions, database, secrets and bypass tokens go with it, straight away, and none of it can be restored. Export the database first if you need what’s in it. The app’s entries stay in the audit log until they age out. Deleting takes an app owner, or a workspace owner or admin.

How roles combine

The two kinds of role answer two different questions.

Who can open the app. Only the app roles and the visibility count here. The platform lets a person in when the app is shared with them, or when the app is open to the workspace and they are a member. A workspace owner or admin with no app role can’t open a private app. They can share it with themselves, since they manage every app:

jiayang share acme/notes bob@example.com

bob@example.com can now use acme/notes as viewer.

Who can change the app. Here a workspace owner or admin counts as an owner of every app in the workspace. They can deploy, share and delete any app without an app role of their own. Everyone else needs the app role for the job: editor to deploy, owner to share.

Some consequences:

Your role in the identity token is your app role. On an app open to the workspace, a member with no app role of their own gets viewer.
jiayang app list acme shows owners and admins every app in the workspace. Members see the apps shared with them and the apps open to the workspace.
Someone you share an app with doesn’t need to be in the workspace. They can open the app in a browser, or call it with jiayang curl, and they can’t see anything else in the workspace.
Removing someone from the workspace also removes every app role they had in it. If they are the only owner of an app, make someone else its owner first:
```
error: They're the only owner of an app here. Make someone else its owner first.
```

Allowed email domains

An owner or admin can limit a workspace to addresses at your company’s domains:

jiayang workspace domains acme example.com

Members and sharing are limited to: example.com

The list also shuts out people who already have access at other domains. Limit who can join covers where it applies and how to clear it.

Leave a workspace

Anyone can leave a workspace by removing their own address with jiayang workspace remove. The last owner can’t, and neither can the only owner of an app. See Leave a workspace.

Limits

The plan sets how many members and apps a workspace can have. Free allows 3 members and 3 apps. Adding one more fails with a message that names the plan that allows more:

error: This workspace has 3 members, which is all the Free plan allows. Remove one, or upgrade: Team allows 25 members. Billing: https://app.jiayang.cloud/w/acme/billing

Only new members count. Changing someone’s role never hits the limit. See Limits for every plan’s numbers.

Share an app to give people app roles.
Members and invitations to add people to the workspace.