Teams, projects and API keys
Understand workspace roles, scope, and credentials for automation.
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. |
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. 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.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.