Roles and permissions

Two of the steps ahead are administrator-only and the rest are not, so it is worth knowing the model before you start asking someone for access you may not need.

Three principals

Platform administrator is a flag on the user's profile, not a membership. It is global: it applies across every organization, and the holder needs no membership row to act in one. This is the CXP team's role.

Owner and member are the two membership roles inside an organization. There is no third, and in particular there is no view-only role.

What each can do

Members are operators

The line above is the one that surprises people: a plain member can trigger a production run, connect a customer's OAuth account, change a schedule's cron, and approve a paused human-in-the-loop run.

That is deliberate. Members are the people who operate the agent day to day — the analyst who reruns yesterday's ingest, the ops lead who approves an order. Making them ask an administrator to click Run Now would defeat the point of the platform. What members cannot do is change the shape of the system: create agents, declare what credentials an agent needs, or wire up runtime environments.

If you need someone who can look but not touch, the platform has no such role today. The nearest option is not to add them to the org.

What this means for the walkthrough

Roughly the first half of this tutorial is administrator work, and the second half is not:

• Administrator — creating the org, the runtime environments, the agent record, and its credential requirements (Platform setup, Create the agent).
• Anyone in the org — connecting the credentials the administrator declared, adding schedules, triggering runs, approving waitpoints.

So a developer building an agent needs an administrator for setup, but the customer does not need one to run it. If you are not an administrator, find one before Platform setup — everything from Credentials onwards is open to you.

A fourth actor: the platform maintainer

One task in this tutorial is not performed by any of the three roles above. Registering a zone is a change to the platform's own source plus a redeploy, so it is done by whoever maintains the platform deployment — not through any UI, and not by a platform administrator acting in the browser.

Whether your platform administrator is also a maintainer depends on how your organisation is set up; at a customer's site they are usually different people, and the request has a lead time. Plan for it: it is the one step in the whole tutorial you cannot self-serve, and it blocks the zone going live. See Register the zone.

Everything else — including creating agents and declaring credential requirements — is a platform administrator action in the UI.

Roles inside your zone app

The platform hands your zone the visitor's role claim and then stops. It does not gate anything inside the zone: any member of the org reaches every page with a valid token.

So if your zone has privileged actions — deleting records, approving something, changing configuration — check claims.role yourself, in the server action rather than in the component that renders the button. Remember that a member here is an operator, not a viewer, so "member" is not a safe synonym for read-only. The pattern is in Zone data and tenancy.

Machines are not roles

Three credentials act outside this model entirely, and none of them carries a role:

• The agent API key authenticates a task resolving credentials or calling back.
• The ingest API key authenticates an external system starting or reporting runs.
• The zone JWT authenticates a zone app, scoped to one agent and minted per request for the signed-in user.

A waitpoint, for example, can be completed by a member in the UI, by an external system holding the agent API key, or by a zone app — the first is role-checked, the other two are key-checked. See Architecture and choices.

Next

Project layout — how to structure the repository.