Settings

Settings covers everything in the workspace configuration surface: identity (name, slug, region), environments, team members and roles, API keys, notification preferences, audit digest, AI model integrations, and billing. Most settings are admin-only. Members with the editor role have read access to some settings areas but cannot modify workspace-level configuration.

---

When to use

Use Settings when you need to:

• Add or remove team members
• Create, scope, or revoke API keys
• Configure which events send notifications and on which channels
• Register an AI provider for agent use
• Change data retention policy
• Set up a new environment for staging or development
• Manage your billing subscription

---

Key concepts

Workspace slug — a URL-safe identifier set at workspace creation. It appears in API paths and cannot be changed after creation. Choose carefully.

Environment — a scoping dimension for workflows and agents. Supported values: production, staging, development. The production environment is protected — certain destructive operations require extra confirmation. You can create additional environments but production cannot be deleted.

Role — every member has one role: admin, editor, or viewer. Roles are assigned per workspace; a person can have different roles in different workspaces.

API key scope — workspace API keys carry one or more of 16 named scopes. A key is constrained to exactly the operations its scopes permit.

Model integration — a tenant-level AI provider registration. Once registered, agents reference a model integration by ID rather than embedding per-agent API keys in configuration. This centralises key management for AI providers.

---

Workspace settings

Navigate to Settings → Workspace.

Field	Type	Description
name	string	Human-readable workspace name
slug	string	Immutable URL-safe identifier
defaultRegion	string	data region for data storage
dataRetentionDays	integer	Days to retain run data; minimum enforced by compliance floor
seatLimit	integer	Maximum number of workspace members

API: GET /workspace, PUT /workspace

Only admin can update workspace settings.

---

Environments

Navigate to Settings → Environments.

Environments let you isolate production workflows from staging and development work. Key rules:

• production is always present and is protected from deletion
• You can create additional environments (e.g. staging, development, custom names)
• Environment changes emit a workspace.environment_updated audit event

API: GET /workspace/environments, PUT /workspace/environments

Note: Deploying a workflow directly to production without testing in a non-production environment first is the single most common cause of unexpected behaviour in customer workspaces. Use staging or development for all new workflows until behaviour is validated.

---

Members

Navigate to Settings → Members.

Invite a member

Enter an email address and select a role (admin, editor, or viewer). An invitation email is sent. The invitee must accept via the link before they can access the workspace. Emits member.invited.

Change a member's role

Select the member and choose a new role from the dropdown. Emits member.updated. Role changes take effect immediately on the member's next API call.

Remove a member

Click Remove next to the member. This revokes their access immediately. Emits member.removed. Any API keys they created remain active until explicitly revoked.

GDPR erasure

For GDPR right-to-erasure requests, click Erase next to the member (or call POST /workspace/members/{userId}/erase). This:

1. Removes the member from the workspace
2. Replaces personId in all historical audit events for that user with a tombstone value
3. Emits member.erased (risk: critical)

Only admin can perform erasure.

Warning: GDPR erasure is irreversible. The personId field in historical audit events cannot be restored after erasure. Confirm the request is valid before proceeding.

API: GET /workspace/members, POST /workspace/members, PUT /workspace/members/{userId}, DELETE /workspace/members/{userId}, POST /workspace/members/{userId}/erase

---

API keys

Navigate to Settings → API Keys.

Create an API key

1. Click New API Key.
2. Enter a name (for your reference) and select the scopes the key should have.
3. Copy the key value — it is shown only once at creation.
4. Pass the key in the x-api-key header on API requests.

Emits api_key.created.

Revoke an API key

Click Revoke next to the key (or call DELETE /workspace/api-keys/{keyId}). The key is immediately invalid. Emits api_key.revoked.

All 16 available scopes: workflows:read, workflows:write, runs:read, runs:write, approvals:read, approvals:write, agents:read, agents:write, skills:read, skills:write, connections:read, connections:write, audit:read, workspace:read, workspace:write, secrets:read.

Warning: The secrets:read scope allows the key holder to call POST /secrets/{id}/reveal and retrieve raw secret values. This is always logged as a secret.accessed high-risk event. Assign this scope only to integrations that genuinely require it.

Only admin can create and revoke API keys.

API: GET /workspace/api-keys, POST /workspace/api-keys, DELETE /workspace/api-keys/{keyId}

---

Notifications

Navigate to Settings → Notifications.

Configure per-event notification preferences. Each event type can deliver to one or more channels.

Event types

Event type	Description
run_failed	A workflow run has failed
approval_requested	An approval step is waiting for human action
workflow_deployed	A workflow has been published
mcp_server_degraded	An MCP server health check has failed
secret_rotated	A secret has been rotated

Channels

Channel	Requirement
email	Sent via SES; no additional setup
slack	Requires an active Slack connection in the workspace
webhook	Delivered via bus inbound; requires a configured subscription

API: GET /workspace/notifications, PUT /workspace/notifications

Only admin can modify notification settings.

---

Audit digest

Navigate to Settings → Audit Digest.

Field	Type	Required	Default	Description
enabled	boolean	Yes	false	Activate the scheduled digest
frequency	enum	Yes	—	daily | weekly | monthly
dayOfWeek	integer	Weekly	—	0 (Sunday) to 6 (Saturday)
dayOfMonth	integer	Monthly	—	1 to 28
hourUTC	integer	Yes	—	Hour (0–23) for delivery
includeRiskLevels	array	Yes	—	Subset of low, medium, high, critical
recipients	array	Yes	—	Email addresses

The digest summarises audit events matching the configured risk levels over the period since the last digest. lastSentAt shows the timestamp of the most recent delivery.

API: GET /workspace/audit-digest, PUT /workspace/audit-digest

Only admin can configure the audit digest.

---

Model integrations

Navigate to Settings → Model Integrations.

Model integrations register AI provider credentials at the tenant level. Once registered, agents reference the integration by modelIntegrationId rather than holding per-agent API keys. This means rotating an AI provider API key requires updating a single integration record, not every agent that uses that provider.

Register a model integration

1. Click New Model Integration.
2. Select the provider (e.g. Anthropic, OpenAI, Google, Azure OpenAI).
3. Enter the API key or credential.
4. Save. The integration is now available to select when configuring agents.

API: GET /settings/model-integrations, POST /settings/model-integrations, PATCH /settings/model-integrations/{id}, DELETE /settings/model-integrations/{id}

Only admin can manage model integrations.

---

Billing

Navigate to Settings → Billing.

• Summary — shows current period usage, seat count, and plan details. API: GET /billing/summary.
• Manage subscription — opens the Stripe customer portal for payment method, invoice history, and plan changes. API: POST /billing/portal (returns a redirect URL to the Stripe portal).

Only admin can access billing settings.

---

Common mistakes

• Not revoking API keys when a team member leaves. API keys persist after a member is removed. Audit the API keys list when offboarding a member and revoke any keys they created.
• Using production for initial workflow testing. Always build and test in development or staging.
• Setting dataRetentionDays too low. If run data expires before an audit or incident investigation, you lose the execution history. Consider your compliance requirements before reducing retention.
• Issuing API keys with more scopes than needed. Follow the principle of least privilege. An integration that only reads workflow status needs only workflows:read and runs:read.

---

Troubleshooting

Invited member cannot log in — check that the invitation email was not filtered to spam. Invitations expire after 7 days. Re-invite the member if the link has expired.

Slack notifications are not delivered — confirm there is an active Slack connection in the workspace (status active). If the connection is in error status, re-authorize it in Connections before notifications will resume.

API key is not working after creation — confirm the key is being passed in the x-api-key header (not Authorization: Bearer). The key value is case-sensitive and must be used exactly as shown at creation time.

PUT /workspace returns 403 — only admin can update workspace settings. Confirm the calling user or key has the admin role or the workspace:write scope.

---

Security and permissions

Area	admin	editor	viewer
Workspace settings	Read / Write	Read	Read
Environments	Read / Write	Read	Read
Members — invite / role change / remove	Yes	No	No
Members — GDPR erase	Yes	No	No
API keys	Read / Write	No	No
Notifications	Read / Write	Read	No
Audit digest	Read / Write	No	No
Model integrations	Read / Write	No	No
Billing	Read / Write	No	No

---

Related pages

• Security Model
• Audit Log
• Connections
• API Reference

---

FAQ