Skip to main content
Introduced in v27.11.0.
Workspace assets are files that live inside the workspace folder, next to its automations, pages, and security rules. They are versioned with the workspace: they travel in workspace exports and imports, in Git pushes and pulls, and in deploys to another environment. The published pages of a workspace, their sources, and any file you add yourself are all assets. Assets are different from uploads, which are runtime files (documents produced by an automation, files uploaded by end users) that stay in the environment where they were created.

Folders and default access

An asset path is relative to the workspace assets/ folder. The folder an asset lives in sets its default access: The Builder writes src/, dist/app/, and dist/public/ when you save and publish pages. Keep your own files in other folders, such as img/ or fonts/: a publish replaces the files of these three folders, and removes the files of dist/public/ it did not write.

Access levels

Each asset has one access level, its folder default unless you set another one: The workspace security rules can grant more access on top of these levels.

Share a private asset with organizations and groups

A private asset can be read by the organizations and groups listed in its bindings, besides the workspace members: Bindings use the same principals as the bindings of the runtime access manager. They only match signed-in users: an anonymous session of an organization, such as a visitor of a public chat widget, never matches a binding of this organization. They are not evaluated on an authenticated or public asset, which is already readable by more users, and they only grant reading. A user can only share with their own organizations and their groups: another organization, or * (every organization), is refused with 403, unless the platform allows cross-organization sharing (ALLOW_CROSS_ORG_SHARING, see Environment variables). Platform superadmins share with any organization. The bindings an asset already has are kept, whoever added them: changing its access or labels never fails on them. In the Builder, add bindings in Shared with organizations and groups: select Group then one of the groups of your active organization, or Organization then one of your organizations (a platform superadmin can pick any organization, or Every organization). The binding is added as soon as you pick it; remove it with the cross next to it.

Require a permission of the organization roles

A private asset with bindings can also require an organization permission (orgPermission), named by the workspace <subject>:<action> (for example reports:read): only the members of its organizations and groups whose organization role grants ws:<workspace slug>:<subject>:<action> read it. The permission comes from the role of the active organization of the user, and only counts when this organization is one of the bindings. In the Builder, type it in Permission also required, under the bindings: the field shows the full name to grant in a role of AI Governance. See Require a permission of the organization roles for the wildcards and the rules on its name. Bindings belong to the environment that sets them. They are exported with the asset, so a pre-production and a production environment with the same organizations share them without setting them twice, but an import never replaces the bindings an environment already has for an asset. See Versioning, export, and import. A request for an asset the caller cannot read returns 404, not 403, so that the existence of a restricted path is not disclosed. The published app (dist/app/) is the exception: its URL is the app’s, so an existing file of the app the caller cannot read returns 403, and the platform asks an anonymous visitor to sign in and tells a signed-in user the app is not shared with them.

Upload an asset from the Builder

  1. In Builder, open the workspace and select Files in the sidebar.
  2. Select the Assets tab.
  3. Select Upload an asset and choose a file. The Upload an asset dialog opens.
  4. In Path, enter the location of the file in the workspace assets, for example img/logo.png. An asset already at this path is replaced.
  5. In Who can read this asset?, select Folder default, Private, Signed-in users, or Public. Folder default shows the access it gives at this path. These are the same choices as for publishing pages.
  6. Optional: in Shared with organizations and groups, add the organizations and groups that can read the asset while it is private.
  7. Optional: in Labels, enter comma-separated labels, for example partners, brand. Security rules can match them.
  8. Select Upload. The asset appears in the list with its access and its labels.
To verify the access, select the open icon on the asset row to get its URL, then open this URL in a private browser window: a public asset is displayed, a private or authenticated asset returns 404. To delete an asset, select the trash icon on its row, then select it again to confirm.

Change the access of an asset from the Builder

  1. In Files > Assets, select the shield icon on the asset row. The Asset access dialog opens on the current access of the asset: an asset that follows its folder default shows the access of its folder. The icon is shown only to the users who can update the asset.
  2. In Who can read this asset?, select Folder default, Private, Signed-in users, or Public. Select Folder default to remove an access set on the asset.
  3. If the asset is private, change the organizations and groups in Shared with organizations and groups. When the asset becomes Signed-in users or Public, its organizations and groups are kept, and apply again if it becomes private.
  4. Optional: change its Labels.
  5. Select Save. The asset row shows its new access. The file itself is not uploaded again.

Asset metadata files

An asset that has an access other than its folder default, bindings, labels, or free metadata gets a metadata file next to it, named <asset path>.meta.yml:
The metadata file is versioned and exported with its asset. It is written only when it holds something, removed when the asset gets back to its defaults, and deleted with its asset. The .meta.yml suffix is reserved: you cannot upload an asset whose path ends with it, and a metadata file is never served or listed. A metadata file that cannot be read, or with an unknown sharing value, makes its asset private, even in dist/public/.

Serve assets

An asset is served at:
<workspace-slug> can also be the workspace id. Because the URL is built from the environment API host and the workspace slug, the same relative path, such as assets/img/logo.png, resolves in every environment the workspace is deployed to. The response depends on the asset:
  • Its Content-Type comes from its file extension. An unknown extension is served as application/octet-stream.
  • Every response carries X-Content-Type-Options: nosniff.
  • HTML, SVG, and XHTML files are served with a sandboxing Content-Security-Policy: they never get the session of their visitor, see Prerendered pages and the visitor session. Outside dist/public/, HTML, SVG, XHTML, and XML files are served as downloads (Content-Disposition: attachment).
  • public assets can be cached by shared caches (Cache-Control: public, max-age=300, s-maxage=600, stale-while-revalidate=86400). Other assets are never cached by shared caches (Cache-Control: private, max-age=0, must-revalidate).
  • Except prerendered pages, assets are served with an ETag and a Last-Modified date, and a conditional request for an unchanged asset returns 304.
  • An asset that is not public, requested as a script or a stylesheet by another site, is answered with Cross-Origin-Resource-Policy: same-site: the browser refuses to run it, so another site cannot read it with the session of a signed-in visitor. Images, fonts, and fetch() calls are not affected, so the platform and custom domains can still embed restricted images.

Page URLs in dist/public/

The prerendered pages of dist/public/ are served with clean URLs:
  • A URL that ends with / serves the index.html file of this folder: .../assets/dist/public/about/ serves dist/public/about/index.html.
  • A URL without extension and without a final /, such as .../assets/dist/public/about, is redirected with 301 to the same URL with a final / (a relative Location, such as about/), its query string kept, when the caller can read the index.html file of this folder. It returns 404 otherwise.
In dist/public/sitemap.xml, the {{SITE_URL}} placeholder written by the Builder is replaced on each request with the URL of dist/public/ built from the API_URL of the environment, so the same sitemap is valid in every environment. Without API_URL, the URLs of the sitemap are relative.

Assets of a published app

When a workspace is published as an app, each app version gets a copy of the assets it serves: the deployed app (dist/app/) and the configuration block, with their metadata files. Sources, uploads, and the site are not copied. The configuration UI of an app can then be one of its assets: set the config.block of the workspace to its relative path, such as assets/dist/public/config.js. It must be a single self-contained file: the files next to it are not copied with the app. In the workspaces that install the app, this path resolves to the copy published with the installed app version:
Without version, the latest published version is served. Publishing the workspace again changes nothing for the installed apps until the app itself is published again. Only the versions listed in the app are served: a version dropped from the list (beyond the limit of versions kept per app) is removed from the storage, and the instances installed with it can no longer be updated. The access of the published copy is the one the asset had when the app version was published, and the security rules and roles of the source workspace apply. A user of an installed app who is no collaborator of the source workspace only gets the assets it shares: put the configuration UI in dist/public/, or give it the authenticated access or bindings. The route requires a signed-in user, and serves the asset with the same headers as above.

Manage assets with the API

Every route takes the workspace id in {workspaceId}, and requires a session or an API key, except for serving public assets.
Replace <workspace-id> with the id of the workspace and <token> with a session token or an API key of a workspace owner or editor. An upload accepts files up to ASSETS_MAX_SIZE (20 MB by default) whose type is allowed by ASSETS_ALLOWED_MIMETYPES (text, JavaScript, JSON, XML, images, and fonts by default). Both are set by the platform administrator, see Configuration > Upload and request limits.

Asset events

Each change made through the API emits an event in the workspace, that an automation can listen to: The payload also carries the userId of the caller when the caller is a user. The events can be read by everyone who can read the workspace events, by default its owners and editors, bindings included. Imports, pulls, and rollbacks do not emit one event per asset.

Open assets with security rules

The workspace security rules apply to assets through the assets subject. A rule can match any of these asset fields: For example, this rule lets anyone, including visitors without a session, read the assets labelled partners:
A rule can also be restricted to some callers with a user condition, matched on the signed-in user. For example, this rule lets the signed-in members of the acme and partner organizations, never their anonymous sessions, read the assets labelled partners:
See RBAC > Restrict a rule to some users for the user fields a rule can match. A rule always applies to the assets of its own workspace only. An inverted rule without a role applies to every user, the workspace owners included. See RBAC for the actions of the assets subject.

Versioning, export, and import

Assets and their metadata files are part of the workspace version:
  • A workspace export contains them under assets/, and pushing to Git commits them with the rest of the workspace.
  • Importing an archive adds and replaces assets, and never deletes one. Importing with Prune, pulling from a repository, and rolling back to a version also delete the assets that are absent from the source.
  • A source exported before workspace assets existed, such as an old archive, an old commit of a repository, or an old version, never deletes an asset: its import, pull, or rollback keeps all the assets of the workspace, the published app included, and returns an AssetsKept warning. A source exported since then deletes the assets it does not contain, even when it contains none.
  • An import, a pull, and a rollback bring the access, labels, and metadata of each asset, but never replace the bindings an asset already has in the target environment, even an empty list, nor the permission that goes with them. Bindings from the source, and their permission, are only applied to assets without bindings yet. A prune keeps the bindings, and their permission, of the assets that stay.
  • An imported asset bigger than ASSETS_MAX_SIZE, or whose known file type is not allowed, is skipped: it is missing from the list of imported files, and the copy already in the workspace, if any, is kept.
  • The exclude setting of a repository pull does not apply to assets.
See Versioning for the rest of the workspace version.

Troubleshooting

An asset URL returns 404

The asset does not exist at this path, or the caller cannot read it. Check the path in Files > Assets, then its access: a private asset requires a workspace role or a matching binding, and an authenticated asset a signed-in user. To share it, change its access, add a binding, or add a security rule.

The app says “You don’t have access to this app”

The bundle of the published app (dist/app/) returned 403: the signed-in user is neither a workspace collaborator nor in an organization or group the app is shared with. Change its access in Publish, or add the user’s organization or group to its bindings.

A public asset is still readable after it was made private

public assets can be kept by shared caches, such as a CDN in front of the API, for 10 minutes (s-maxage=600), then served stale for up to a day while they revalidate (stale-while-revalidate=86400): the first request after these 10 minutes can still get the cached copy. Purge the CDN cache for this URL if the asset must disappear at once.

'*.meta.yml' is reserved for asset metadata

The upload path ends with .meta.yml. Choose another path: metadata files are written by the platform.

size must not exceed or mimetype must be one of

The file is bigger than ASSETS_MAX_SIZE, or a type is not allowed by ASSETS_ALLOWED_MIMETYPES: the type sent with the file, or the type of its path extension, the one it is served with. Ask the platform administrator to raise the limit or to allow the type. A path with an unknown extension is only checked on the type sent with the file, and is served as application/octet-stream, as a download.

An HTML file is downloaded instead of displayed

Outside dist/public/, HTML, SVG, XHTML, and XML assets are served as downloads, so that an uploaded document cannot run in the API domain. Publish pages from the Builder to serve them as web pages.

bindings must be an array of { principalType: org | group, principalId }

A binding is neither an organization (a slug, or *) nor a group (organization:group). Bindings cannot target a single user: share the asset with its organization or one of its groups, or give the user a workspace role.