API scopes and key management
Find the scope an operation needs, then select it on your key in the matching XY environment.
Create and update API keys
- In XY, select your organization and open Organization settings → API Keys.
- Create a key, or choose Edit key on an existing key. Select the required scopes and choose Save changes.
- Use
GET /api/v1/auth/checkwith that key to confirm its environment, credential type, and scopes.
Key management requires API-key access granted in that organization. Available scopes are limited by your current permissions and the selected key type. If a scope is unavailable, ask your organization’s authorized API-key manager.
Existing keys keep their selected scopes when new scopes become available. Editing scopes does not replace the key value. Rotate key replaces the secret and immediately revokes the old key; update your client to use the replacement.
API-key creation, listing, scope changes, rotation, and revocation are managed through this settings screen. They are not public REST operations. The /api/v1/credentials routes manage Password Vault references used by workflows, rather than API keys.
XY staff automations
Staff-only operations have a separate authenticated reference: Organization settings → API Keys → Documentation → Internal operations. Sign in with current STAFF membership to view its REST routes, MCP tools, required scopes, and setup steps.
Use a personal key or MCP OAuth for staff operations. The credential’s selected scopes and your current access in each target organization are checked separately. A public API scope or a service key does not grant staff access.
Public API scope reference
This reference is generated from the same scope catalog and operation metadata as the API. Every interactive operation also states its required scope. Additional scopes and resource permissions may apply to particular actions; read the operation’s full description before calling it.
“Allowed” means eligible for that credential type within your current permission ceiling. It does not mean automatically granted. The operation list groups routes by their required scopes; some scopes add authority to actions documented on those routes.
| Scope and operations | Personal key | Service key | MCP OAuth |
|---|---|---|---|
agent_requests:approve
Approve a submitted custom request and atomically start one durable Planner build. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
agent_requests:read
Read custom Marketplace workflow requests. Operations requiring this scope (5)
|
Allowed | Allowed | Allowed |
agent_requests:write
Create, edit, publish, and close your custom Marketplace workflow requests, and answer XY's clarifications. Operations requiring this scope (7)
|
Allowed | Allowed | Allowed |
agents:read
List and inspect Marketplace agents available to this organization. Operations requiring this scope (4)
|
Allowed | Allowed | Allowed |
authoring:read
Read durable workflow-authoring sessions, messages, progress, and draft references. Operations requiring this scope (4)
|
Allowed | Allowed | Allowed |
authoring:submit
Send an explicitly accepted immutable Workflow Spec into a governed workflow request or Planner build. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
authoring:write
Start and continue plain-language workflow-authoring sessions, review drafts, and stop active work. Operations requiring this scope (5)
|
Allowed | Allowed | Allowed |
browser:control
Send keyboard and pointer input to Browser Studio. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
browser:debug
Run raw Chrome DevTools Protocol commands. Operations requiring this scope (1)
|
Unavailable | Allowed | Allowed |
browser:read
Read Browser Studio sessions, tools, and drafts. Operations requiring this scope (4)
|
Allowed | Allowed | Allowed |
browser:trust
View this organization's trust profiles and sign-in alerts, open human sign-in sessions, explicitly read or paste clipboard text, and finish or cancel those sessions. Operations requiring this scope (8)
|
Allowed | Allowed | Allowed |
browser:write
Create sessions, run commands and prompts, and apply drafts. Operations requiring this scope (6)
|
Allowed | Allowed | Allowed |
browser_sessions:read
Read login status and retrieve short-lived authenticated browser state. Operations requiring this scope (4)
|
Unavailable | Allowed | Unavailable |
browser_sessions:write
Start configured portal logins for portable browser handoff. Operations requiring this scope (2)
|
Unavailable | Allowed | Unavailable |
credentials:read
List safe Password Vault credential-reference metadata visible to this identity, never secret values. Operations requiring this scope (3)
|
Allowed | Allowed | Allowed |
credentials:write
Create, rotate, and revoke secure credentials used by workflows. Operations requiring this scope (4)
|
Unavailable | Allowed | Allowed |
dashboards:propose
Create or revise a governed dashboard proposal for human review. This scope cannot approve or publish a dashboard. Operations requiring this scope (5)
|
Allowed | Allowed | Allowed |
dashboards:read
Ask the governed dashboard agent to analyze organization workflow data. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
executions:read
Read permitted workflow metadata, execution state and results. Operations requiring this scope (10)
|
Allowed | Allowed | Allowed |
executions:write
Start approved agent and workflow executions and cancel individual workflow runs. Operations requiring this scope (3)
|
Allowed | Allowed | Allowed |
installations:read
Read installation state and connected sources. Operations requiring this scope (5)
|
Allowed | Allowed | Allowed |
installations:write
Install agents and manage their sources and authorization actions. Operations requiring this scope (11)
|
Allowed | Allowed | Allowed |
integrations:connect
Attach encrypted credential references to integrations and manage connections. Operations requiring this scope (4)
|
Unavailable | Allowed | Allowed |
integrations:generate
Use supplied API documentation to discover, generate, and validate an organization integration. Operations requiring this scope (7)
|
Unavailable | Allowed | Allowed |
integrations:promote
Make a validated organization-owned integration live for workflow execution. Operations requiring this scope (1)
|
Unavailable | Allowed | Allowed |
integrations:read
Browse integration definitions, capabilities, factory runs, and safe connection metadata. Operations requiring this scope (10)
|
Allowed | Allowed | Allowed |
logs:read
Read this organization's own log records, and summaries of them. Log lines may carry PHI, so this is granted by name rather than riding along with the other read scopes. Operations requiring this scope (2)
|
Allowed | Allowed | Allowed |
metrics:read
Read Marketplace agent and installation metrics. Operations requiring this scope (10)
|
Allowed | Allowed | Allowed |
planner:control
Send keyboard and pointer input to a Planner browser session. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
planner:export
Export the full reusable Planner build artifact. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
planner:promote
Promote completed builds or save reusable templates. Operations requiring this scope (6)
|
Unavailable | Allowed | Allowed |
planner:read
List builds, durable state, and public build events. Operations requiring this scope (6)
|
Allowed | Allowed | Allowed |
planner:view
Open the live noVNC view for a Planner browser step. Operations requiring this scope (2)
|
Allowed | Allowed | Allowed |
planner:write
Start, resume, test, accept, reject, and abandon Planner builds. Operations requiring this scope (15)
|
Allowed | Allowed | Allowed |
queue_ui:approve
Approve an exact design version and its returned 16-character resolved hash using a system API key, guarded by the expected live publication receipt. Sensitive delegated authority, recorded as system approval rather than human review. Does not publish; personal keys and user-bound OAuth cannot use this scope. Operations requiring this scope (1)
|
Unavailable | Allowed | Unavailable |
queue_ui:publish
Publish an exact approved design or restore a publication receipt, including the baseline, with authorized personal or system access. Approval and target publication permissions are checked separately; this scope does not grant approval. Operations requiring this scope (2)
|
Allowed | Allowed | Allowed |
queue_ui:publish_code
Activate or restore an exact reviewed executable Queue UI artifact release. This stronger permission is checked in addition to queue_ui:publish whenever the persisted target contains executable artifacts. Additional permission for actions described in the interactive reference. |
Allowed | Allowed | Allowed |
queue_ui:read
Read eligible workflows, queue designs, versions, and progress events with authorized personal or system access. Operations requiring this scope (6)
|
Allowed | Allowed | Allowed |
queue_ui:write
Create and revise queue designs, stop generation, or close a design and clean up previews with authorized personal or system access. Operations requiring this scope (4)
|
Allowed | Allowed | Allowed |
recordings:read
Download the reusable recorder and read recordings created through this organization's recording invitations. Operations requiring this scope (3)
|
Allowed | Allowed | Allowed |
recordings:write
Create and revoke email-bound recording invitations for this organization. Requires a service API key. Operations requiring this scope (2)
|
Unavailable | Allowed | Unavailable |
records:read_values
XY staff only: read the values of production queue records (entity data, which can include personal and patient data) for workflows in this organization. Others, and API keys, see the fields but not the values even when granted it. Additional permission for actions described in the interactive reference. |
Allowed | Allowed | Allowed |
review_items:read
Read human-review work produced by executions. Operations requiring this scope (2)
|
Allowed | Allowed | Allowed |
review_items:revise
Reverse an already-resolved review decision. Separate from deciding open work because it rewrites a completed outcome. Additional permission for actions described in the interactive reference. |
Allowed | Allowed | Allowed |
review_items:write
Submit decisions for human-review work. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
schedules:read
List organization workflow schedules and their recent runs. Operations requiring this scope (2)
|
Allowed | Allowed | Allowed |
schedules:write
Create, update, pause, resume, trigger, and delete workflow schedules. Operations requiring this scope (6)
|
Allowed | Allowed | Allowed |
sessions:read
Read coordinated session state and replayable events. Queue designs also require queue_ui:read. Operations requiring this scope (5)
|
Allowed | Allowed | Allowed |
sessions:write
Send attributed session messages. Queue designs also require queue_ui:write. Operations requiring this scope (1)
|
Allowed | Allowed | Allowed |
sms:read
Read message bodies delivered to this organization's dedicated VoIP inbox. Operations requiring this scope (1)
|
Unavailable | Allowed | Allowed |
usage:read
Read Planner, Integration Factory and browser operation summaries, plus operating-cost reports for permitted workflows when the organization has separate cost approval. Operations requiring this scope (3)
|
Allowed | Allowed | Allowed |
webhooks:read
Read organization webhook subscriptions and delivery history. Operations requiring this scope (5)
|
Allowed | Allowed | Allowed |
webhooks:write
Create, test, change, delete, rotate, and redeliver organization webhooks. Operations requiring this scope (6)
|
Allowed | Allowed | Allowed |