Teams, projects and API keys

Select the intended team and project before creating assets or running a workflow. Membership and permissions apply independently of whether you know a resource ID.

Team roles

Base role	Intended access
Business user	Chat, run existing scenarios or generators, and download results; no asset authoring or administration.
Member	Read resources and author templates, scenarios, data and other project assets; no team or membership administration.
Admin	Manage members, roles and content; destructive team ownership operations remain owner-only.
Owner	Full team permissions, including ownership operations.

Every role, and every API key role, holds audit:record, so the agent's tool calls are on the audit trail whoever drives it. It grants nothing else.

A business user also fills in input sets, saves them as datasets and syncs those versions to a connected Tosca Cloud through integration:run. That permission does not let them read other connections (integration:read) or create, edit or delete one (integration:write).

Custom roles add permissions to a base role; they do not subtract permissions already granted. Use the Business user base role for a consumer who should run approved resources without editing them. See Run shared datasets and Team invitations.

Custom roles

A custom role is a named set of permissions held in addition to a base role. Build one in Settings → Roles, which is available to anyone holding role:write or member:write, then assign it to a member alongside the base role they already have.

Custom roles only ever add. Nothing a custom role lists can be taken back by another role, so a deliberately restricted tier has to be a base role instead - that is what Business user is for. A business user holding a custom role still gets everything that role lists, so read a member's effective permissions rather than inferring them from the base role.

Role definitions are portable between workspaces. Export writes the team's custom roles as a versioned JSON document of names, descriptions and permissions; IDs, team references, system roles and member assignments are deliberately excluded, so the file carries a policy rather than a workspace. Import creates the definitions the destination does not have and skips every name it already has, system role names included. It never overwrites or merges, and a malformed document imports nothing at all rather than part of itself. Re-importing an edited file will not update a role that already exists: change that one in place.

Plan permissions

Writing a plan, running one and approving one are three separate permissions, so a workspace can name an approver who is not the author and a consumer who runs approved plans without being able to rewrite them.

Permission	What it allows
`plan:read`	Open Plans, and read a plan with its runs and sign-offs.
`plan:write`	Create, edit and delete a plan. It does not carry approval or execution.
`plan:run`	Start a plan run or a readiness check, and cancel a run in flight.
`plan:approve`	Approve a plan, sign off a check and accept a completed run.

Approval has its own endpoint, POST /plans/{id}/approve. A plan is not approved by patching its status: PATCH /plans/{id} and POST /plans/save refuse to set approved and answer PLAN_APPROVE_VIA_APPROVE_ROUTE. That keeps every approval in one place, where the permission is checked and the approver is taken from the session rather than supplied by the caller. Older desktop builds still approve through POST /plans/{id}/status with status: "approved"; that route checks plan:approve, applies the same flow verification and writes the same audit entry, so it is a second door to the same check rather than a way around it. A caller who can edit a plan but not accept one gets 403 PLAN_APPROVAL_FORBIDDEN.

Members, admins and owners hold all four permissions. A custom role that already had plan:write was granted plan:run and plan:approve when your workspace was upgraded, so no role lost an ability; narrow those roles afterwards if you want authoring and approval held by different people. The Business user preset is deliberately unchanged, and plan:run can be added to it with a custom role.

Two limits are worth stating. A READ_WRITE API key holds every plan permission, plan:approve included, so separation of duties binds people rather than keys: do not treat an automation key as an independent approver. And four-eyes review - requiring the approver to be someone other than the author - is expressible with these roles but is not enforced by the product.

API keys

A workspace administrator creates API keys for automation in Settings → Team, under API keys. Choose the narrowest useful scope - project, team or user - and role:

READ_ONLY: read permissions, plus audit:record so the agent calls a read-only key makes are recorded.
READ_WRITE: ordinary read, write and execution, excluding team/member/role/API-key/license administration and key-map reversal.
ADMIN: full API-key permission set; use only when the automation actually requires administration.

Send keys in X-API-Key. The official SDKs read DATAMAKER_API_KEY. Scope headers such as X-Project-Id select a permitted project; they do not widen a key's access.

Keep keys in a secret manager or CI secret, rotate them when necessary and revoke unused keys. Do not embed them in browser code, templates, screenshots or shared scenarios.

Scenario-run credentials

The runner injects a short-lived credential and the project, team, scenario and job context. It is bound to the run for scenario, log and workspace operations, but otherwise carries project READ_WRITE privileges. Treat it as a privileged secret, not as a harmless run identifier. It cannot start another scenario run.

Diagnose access failures

A 401 usually indicates missing or rejected credentials. A 403 can mean missing permission or approval; a resource outside your scope may appear not found. Verify the selected host, team and project before asking for broader privileges.