Scopes decide what a credential can read or do. Use the narrowest set the client needs: a workflow-health dashboard needs workflows:read, not your lead data.
#Read scopes
| Scope | Grants |
|---|---|
workspace:read | The workspace’s identity and non-sensitive metadata. |
tables:read | Table definitions, fields, row counts, and row IDs and timestamps. |
forms:read | Form definitions, field presentation, submission counts, and submission IDs and timestamps. |
workflows:read | Workflow metadata, versions, run summaries, and step outcomes. |
approvals:read | Approval and decision summaries: status, source, priority, decision kind, timestamps. |
records:read | Decision-record summaries: category, action, resource, actor, timestamp. |
agents:read | Agent registry entries, versions, status, and usage and eval summaries. |
integrations:read | Connected integrations and connection health. Never credentials. |
files:read | File metadata: name, content type, size, creator, timestamp. |
optimization:read | Optimization suggestions for your workflows: status, workflow, timestamps. |
payloads:read | The values behind the read scopes above. Grants nothing on its own. |
#Action scopes
| Scope | Grants | Available on |
|---|---|---|
workflows:execute | Start a workflow run. | REST and MCP |
approvals:request | Submit a proposal to the approval queue. | REST and MCP |
forms:submit | Submit a form; the values become a row in its table. | REST |
workflows:create | Draft new workflows with an AI client. | MCP |
workflows:update | Revise existing workflows with an AI client. | MCP |
approvals:decide | Approve or reject a pending proposal, or undo the decision within 10 seconds. | REST and MCP, OAuth connections only |
optimization:decide | Accept or dismiss an optimization suggestion, or undo either. | REST and MCP, OAuth connections only |
approvals:decide and optimization:decide can’t be granted to an API key. Only a person, signed in through an OAuth connection and confirming each decision, can approve, reject, or change a workflow’s configuration.
#Payload access is additive
payloads:read unlocks values only for resources the credential can already see. Pair it with the matching domain scope:
| To read | You need |
|---|---|
| Table row values | tables:read and payloads:read |
| Form submission values | forms:read and payloads:read |
| Workflow definitions and run step input/output | workflows:read and payloads:read |
| Approval proposals, context, edits, and feedback | approvals:read and payloads:read |
| Decision-record old and new values | records:read and payloads:read |
| Agent instructions, memory, feedback, eval runs, and conversation events | agents:read and payloads:read |
| File download links | files:read and payloads:read |
A key with payloads:read and only workflows:read can read run inputs but still can’t read a single table row.
Table and form data is whatever your team put there. Rills can’t tell which of your columns hold sensitive information, so a credential with tables:read and payloads:read can read every value in every table. That usually includes prospect names, emails, and notes.
#Scopes for analytics queries
POST /query checks scopes per dataset:
| Dataset | Required scopes |
|---|---|
tableRows | tables:read, payloads:read |
formSubmissions | forms:read, payloads:read |
workflowExecutions | workflows:read |
approvals | approvals:read |
decisionRecords | records:read |
agentConversations | agents:read |
files | files:read |
Table and form aggregates need payloads:read because a count filtered on a column reveals that column’s values.
#Presets
The key dialog offers two starting points:
- Metadata only: all ten domain read scopes, without
payloads:read. - Full workspace read: the same scopes plus
payloads:read.
Neither preset includes action scopes. Add workflows:execute or approvals:request explicitly when a client needs them.
#Roles and OAuth connections
An OAuth connection gets the scopes you approved, limited by your current role:
- Viewers can grant every read scope, including
payloads:read, andforms:submit. - Members, admins, and owners can also grant
workflows:execute,workflows:create,workflows:update,approvals:request,approvals:decide, andoptimization:decide.
If your role changes, the connection’s effective access changes with it.
#Never returned
No scope, including payloads:read, returns:
- workspace secret values;
- integration API keys, client secrets, access tokens, or refresh tokens;
- Rills API key values or hashes;
- webhook signing secrets or tokenized URLs;
- passwords or session data;
- internal billing identifiers or platform-administration data.
Workflow definitions can mention a secret or connection by reference, but never its value. Team, billing, notification, and secrets settings aren’t part of the API.