What you can do
You already have a workspace from Getting Started. Picture Maya's homepage hero sitting in Production on Default Project. This page is how that hero moves through Development and Staging — and how her site asks for it with a token.
Two everyday jobs:
- Ship the hero through the pipeline. Draft a new layout in Development, preview it with a
dev.token, Promote to Staging, publish for QA, then Promote to Production and publish for the live site. Each environment has its own token. - Give the marketing site and the product app different keys. Register a second app next to
Default App. Tokens stay separate, so you can disable one site without touching the other.
After Get Started you already have the Production token for Default App. Copy it, embed the published Default Widget, and you are shipping. The rest of this page is when you want a safer preview, a second consumer, or another project.
How environments and tokens think
The nest you already know still holds: organization → team → project → environment. Getting Started created Default Project, three environments, and Default App. This page is where content and keys live.
- Project. Holds environments and the CSS catalogs that seed the next widget. Most work stays in Default Project.
- Environment. Development, Staging, or Production. Widgets, collections, and widget selection rulesets live here — not on the team.
- App. A consumer you register on the team — a marketing site, a product app, a docs host. Get Started created
Default App. - Token. One key for one app in one environment. Your site holds that key and asks that environment for a widget.
Here is the case that surprises people. You open Development looking for the Default Widget and it is empty. That is expected. Get Started — and every extra team — creates the Default Widget in Production, the environment you land in. Staging and Development start empty of widgets. Media you upload is already available in all three — media belongs to the team. The widget does not. See Organizations & Teams.
Development tokens (and tokens for any environment that is not Staging or Production) are stored with a dev. prefix. Staging and Production tokens have no prefix. That prefix tells @rulecms/widget-react to load live drafts instead of published snapshots. Use the draft widget key with a dev. token. Use a published key with a Staging or Production token.
Copy the token for an environment
This is the first complete path: you leave with the key your site already has. You need an Apps and Tokens group at View, Manage, or Admin. View is enough to copy. Manage is enough to create another token.
- From the dashboard, open the team under Your Teams with Go to Team. You land on Overview.
- On the
Default Projectcard, the environment list defaults to Production. Click Go. (Manage Project opens the same Production home.) - You are on the environment home. Orange cards come first: Widgets, Collections, Widget Selection Rulesets, and CSS Styles. Under CSS catalog are the project templates — CSS Variables, Fonts, and the rest. Further down, the Tokens card is the key for this environment.
- On Tokens, click View Tokens. The list is pre-filtered to this environment (
environmentIdin the URL). Opening tokens from External App Registry pre-filters byappIdinstead. - Find the
Default Approw. Click Show, then Copy. That is a safe stop.
The Production token has no dev. prefix. Pair it with the widget's published key after you publish. For a live Development draft, switch the environment home to Development — use the switcher under the project name — and copy that token instead. It starts with dev.. See Development Integration.
Promote and publish are different buttons. On a widget in Development, Promote to Staging copies the draft into Staging. On Staging, Promote to Production does the same for Production. Publishing creates the immutable snapshot a Staging or Production token fetches. Copy To is only for extra environments you named yourself — not Staging or Production. The widget guides cover the clicks; Publishing covers the snapshot.
When you reach for it
The first path above is copy the token you already have. These are the other levers, named as jobs.
| What you need | When you reach for it |
|---|---|
| Another project | A second line of work that should not share environments with the homepage hero. On Overview, the All Projects card has Create New — or open All Projects and click Create Project. Type a Name a teammate would recognize. Description is optional. Submit with Create Project. You get Development, Staging, and Production, plus a Default Widget in Production. Tokens are not created for the new project — add them from the Tokens card, picking Default App (or another app) and the new environment. |
| Another environment | A sandbox that is not Development, Staging, or Production. On environment home, click Create New Environment. Type a unique Name (case does not count) and an optional description. Submit with Create Environment. No Default Widget and no token are created. Add a token yourself. Because the name is not Staging or Production, that token gets a dev. prefix and loads live drafts. |
| Another app | The marketing site and the product app should not share a key. On Overview, under Team Resources, open External App Registry → Register App. Type a Name — “Marketing site” — and an optional description. Submit with Register App. Then create a token per environment you will call. Rename Default App later with Edit Registered App if the first name no longer fits. |
| Enable or disable a token | On the token card, the checkbox reads Enabled or Disabled. A disabled token rejects public API requests. Only one token can be enabled for the same app and environment. Disable the current one before you can enable another — or before Generate Token will create a replacement. |
| Rename the project | On environment home, Rename opens the project edit form. Change Name or description and Update Project. The three environments stay put. |
Creating a project needs a Projects group at Manage or Admin. Creating an environment needs the same: Manage Projects or Admin Projects. There is no Manage or Admin group under Project Environments — only View Project Environment, which you need to open the environment home where Create New Environment sits. On Staging or Production home, that is View Project Environment Staging or View Project Environment Production. Creating an app or a token needs Apps and Tokens at Manage or Admin. Staging and Production have their own groups for those environments when you want to split who can ship there.
An agent can create that project, environment, app, and token after you connect MCP. The same permissions apply. The walkthrough is Projects through MCP.
Project CSS is the template for the next widget
The CSS catalog on environment home belongs to the project, not to one environment. When you create a widget, RuleCMS copies that catalog onto it. After that the widget owns the copy. Editing the project catalog does not change widgets that already exist — those widgets pull updates later from their own CSS Settings.
This page is not the CSS manual. Open the guide for the catalog you are editing:
- CSS Variables — named custom properties, the usual starting point.
- Class Definitions, Fonts, Keyframes, Position try, CSS Properties, Themes, Cascade layers, and Widget chrome — the rest of the project templates on that same home.
What to read next
This page is the pipeline and the keys. Widgets, publish, and embed consume what you copied.
- Widgets — Create and manage the pieces of content an environment holds, starting from the Production Default Widget or a new draft in Development.
- Publishing — How a widget becomes the snapshot a Staging or Production token fetches.
- Development Integration — Preview live Development drafts with a
dev.token and the draft widget key — no publish step. - API Reference — The request your app sends with a Staging or Production token and a published key.
- CSS Variables — The project token catalog, copied onto the next widget you create.
- Widget Selection Rulesets — Choose which published widget a visitor sees, using the same environment and token habits.
How this fits
People and extra teams are Organizations & Teams. This page is where content and keys live. A project does not replace a widget. An environment is where that widget sits. A token is how a registered app asks for it.
Copy the Production token. Open the Default Widget. When you want a safer preview, switch to Development and use the dev. key. Register a second app when two sites should not share one.