Share an app

Sharing gives one email address a role on one app. The edge checks that list on every request, so only the people on it get past the sign-in.

Share with one person

jiayang share acme/hello sam@example.com

sam@example.com can now use acme/hello as viewer.

Sam gets an email with the app’s link. They open it, sign in with a code sent to that address, and the app loads. There is no password and no account to make first.

A viewer doesn’t have to be a member of your workspace. They reach the app by its link, and nothing else in the workspace is visible to them. To find it again, they sign in to the dashboard, which lists it under Shared with you, or run:

jiayang app list --shared

acme/hello                               viewer  https://hello--acme.jiayang-apps.cloud  shared by you@example.com

Pick a role

--role sets what they may do. The default is viewer.

Role	What they can do
viewer	Use the app.
editor	Also deploy it, and manage its configuration, secrets and tokens.
owner	Also share it, and delete it.

Your app is told the caller’s role on every request, in the identity token. The SDKs read it for you.

Editors and owners have to be members of the workspace first:

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

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

Add them with jiayang workspace add, as Members and invitations shows, then share again.

To change someone’s role, share with them again and give the new one. A role change sends no email.

See who has access

jiayang access acme/hello

owner    ana@example.com
editor   dana@example.com
viewer   lee@example.com
viewer   sam@example.com

The list shows everyone with their own grant. Whoever created the app is its first owner. jiayang --json access acme/hello adds who shared the app with each person, and when.

Open it to the whole workspace

jiayang app visibility acme/hello workspace

Everyone in acme can view acme/hello.

Every member of the workspace can now open the app as a viewer. People with their own grant keep their role.

To close it again:

jiayang app visibility acme/hello private

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

New apps start private. jiayang deploy --create --visibility workspace makes an app that starts open to the workspace, and so does jiayang app create --visibility workspace.

Take access away

jiayang unshare acme/hello lee@example.com

lee@example.com no longer has access to acme/hello (takes effect within 60 seconds).

Within a minute, Lee’s requests are refused. A WebSocket, stream or download Lee has open is closed too. From then on the app answers them like this:

jiayang curl acme/hello

not found

jiayang curl prints the status, 404 Not Found, on stderr. Lee isn’t a member of the workspace, so the app answers as if it weren’t there: someone outside the workspace can’t tell which of its apps exist. A member of the workspace gets 403 Forbidden instead.

An app always keeps at least one owner. Removing the last one is refused:

error: An app needs at least one owner.

If the person had no grant, you see:

error: not found: nothing of acme/hello is shared with lee@example.com, or it isn't an app you can see

Removing someone from the workspace also removes every grant they had on its apps. See Members and invitations.

Unsharing also ends the bypass tokens Lee made for the app, unless the app is open to the whole workspace and Lee is still a member: then they work as viewer tokens. Making Lee a viewer turns an editor token of theirs into a viewer token for as long as they stay one. See When its maker loses access.

How fast a change lands

Change	When it takes effect
Share, or open the app to the workspace	Within 60 seconds
Unshare, make the app private, or remove a member	Within 60 seconds, open connections included
Revoke a bypass token	On the token’s next request. A connection already open with it closes within 15 seconds
Take away the access of someone who made a bypass token	On the token’s next request, as for a revoke. See When its maker loses access

The edge keeps a browser’s answer for under a minute, then asks the control plane again. Many copies of the edge run in each Cloudflare location, each with answers of its own, so once one of them refuses a person, the others in that location stop using the answer they kept: from the first refused request on, the person is refused there every time, not just now and then. Open connections are checked while they run and closed once access ends. A connection opened with a bypass token or a CLI session is checked every 10 seconds, so it closes within 15 seconds of the token being revoked, the session ending or the person’s access being taken away.

Who can share

App owners, and the workspace’s owners and admins, can share an app, unshare it and change its visibility. An editor who tries gets:

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

Note

Workspace owners and admins manage sharing on every app in the workspace, but the edge doesn’t let them into a private app on that alone. A person gets in through their own grant, or as a member when the app is open to the workspace. To open a private app you manage, share it with yourself.

Share only inside your company

When the workspace has allowed email domains, you can only share with addresses at those domains:

jiayang share acme/hello pat@gmail.com

error: This workspace only shares with its allowed email domains.

The same list also shuts out existing grants at other domains. See Limit who can join.

Invitation emails

Each new share sends one email, with the app’s address as the link. Sharing with the same person again sends nothing.

A workspace sends at most 50 invitation emails a day, and one person sends at most 100 a day across all their workspaces. Past either, the share still takes effect and no email goes out. The dashboard tells you when that happens, so you can send the link yourself.

If nothing is deployed yet, the link won’t open until a version is live.

In the dashboard

Open the app and go to Sharing.

• Who can open it switches between the people the app is shared with and everyone in the workspace. Opening it to the workspace asks you to confirm.
• People lists every grant. Type an email, pick Viewer, Editor or Owner, and select Share. Each row has a role menu and a remove button.

Related

• Workspaces and roles: what each workspace role can do.
• How access works: the path of one request through the edge.
• Tokens for scripts and machines: access for something that can’t sign in.
• Audit log: every share and unshare is in it, as grant.put and grant.remove.