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

  1. In XY, select your organization and open Organization settings → API Keys.
  2. Create a key, or choose Edit key on an existing key. Select the required scopes and choose Save changes.
  3. Use GET /api/v1/auth/check with 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 operationsPersonal keyService keyMCP OAuth
agent_requests:approve

Approve a submitted custom request and atomically start one durable Planner build.

Operations requiring this scope (1)
  • POST /api/v1/agent-requests/{request_id}/approve-planner
Allowed Allowed Allowed
agent_requests:read

Read custom Marketplace workflow requests.

Operations requiring this scope (5)
  • GET /api/v1/agent-requests
  • GET /api/v1/agent-requests/{request_id}
  • GET /api/v1/agent-requests/{request_id}/deployments
  • GET /api/v1/agent-requests/{request_id}/usage
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/change-requests/{change_id}
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)
  • PATCH /api/v1/agent-requests/{request_id}
  • POST /api/v1/agent-requests
  • POST /api/v1/agent-requests/bulk
  • POST /api/v1/agent-requests/{request_id}/close
  • POST /api/v1/agent-requests/{request_id}/messages
  • POST /api/v1/agent-requests/{request_id}/publish
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/change-requests
Allowed Allowed Allowed
agents:read

List and inspect Marketplace agents available to this organization.

Operations requiring this scope (4)
  • GET /api/v1/agents
  • GET /api/v1/agents/{agent_id}
  • GET /api/v1/discovery/agents
  • POST /api/v1/discovery/matches
Allowed Allowed Allowed
authoring:read

Read durable workflow-authoring sessions, messages, progress, and draft references.

Operations requiring this scope (4)
  • GET /api/v1/authoring/sessions/{session_id}
  • GET /api/v1/authoring/sessions/{session_id}/drafts
  • GET /api/v1/authoring/sessions/{session_id}/events
  • GET /api/v1/authoring/sessions/{session_id}/messages
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)
  • POST /api/v1/authoring/sessions/{session_id}/submit
Allowed Allowed Allowed
authoring:write

Start and continue plain-language workflow-authoring sessions, review drafts, and stop active work.

Operations requiring this scope (5)
  • POST /api/v1/authoring/sessions
  • POST /api/v1/authoring/sessions/{session_id}/cancel
  • POST /api/v1/authoring/sessions/{session_id}/drafts/accept
  • POST /api/v1/authoring/sessions/{session_id}/drafts/discard
  • POST /api/v1/authoring/sessions/{session_id}/messages
Allowed Allowed Allowed
browser:control

Send keyboard and pointer input to Browser Studio.

Operations requiring this scope (1)
  • POST /api/v1/browser/sessions/{session_id}/control
Allowed Allowed Allowed
browser:debug

Run raw Chrome DevTools Protocol commands.

Operations requiring this scope (1)
  • POST /api/v1/browser/sessions/{session_id}/cdp
Unavailable Allowed Allowed
browser:read

Read Browser Studio sessions, tools, and drafts.

Operations requiring this scope (4)
  • GET /api/v1/browser/recorded-tasks
  • GET /api/v1/browser/sessions/{session_id}
  • GET /api/v1/browser/sessions/{session_id}/draft
  • GET /api/v1/browser/tools
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)
  • DELETE /api/v1/browser/trust/sessions/{session_id}
  • GET /api/v1/browser/trust/profiles
  • GET /api/v1/browser/trust/sessions/{session_id}
  • GET /api/v1/browser/trust/sessions/{session_id}/clipboard
  • GET /api/v1/browser/trust/sign-ins
  • POST /api/v1/browser/trust/sessions
  • POST /api/v1/browser/trust/sessions/{session_id}/clipboard
  • POST /api/v1/browser/trust/sessions/{session_id}/finalize
Allowed Allowed Allowed
browser:write

Create sessions, run commands and prompts, and apply drafts.

Operations requiring this scope (6)
  • DELETE /api/v1/browser/sessions/{session_id}
  • POST /api/v1/browser/sessions
  • POST /api/v1/browser/sessions/{session_id}/apply
  • POST /api/v1/browser/sessions/{session_id}/commands
  • POST /api/v1/browser/sessions/{session_id}/prompts
  • POST /api/v1/browser/sessions/{session_id}/prompts/cancel
Allowed Allowed Allowed
browser_sessions:read

Read login status and retrieve short-lived authenticated browser state.

Operations requiring this scope (4)
  • GET /api/v1/browser-session-portal-types
  • GET /api/v1/browser-session-portals
  • GET /api/v1/browser-sessions/{handoff_id}
  • GET /api/v1/browser-sessions/{handoff_id}/artifact
Unavailable Allowed Unavailable
browser_sessions:write

Start configured portal logins for portable browser handoff.

Operations requiring this scope (2)
  • POST /api/v1/browser-sessions
  • POST /api/v1/browser-sessions/{handoff_id}/mfa
Unavailable Allowed Unavailable
credentials:read

List safe Password Vault credential-reference metadata visible to this identity, never secret values.

Operations requiring this scope (3)
  • GET /api/v1/browser-session-portals
  • GET /api/v1/credentials
  • GET /api/v1/credentials/{credential_id}
Allowed Allowed Allowed
credentials:write

Create, rotate, and revoke secure credentials used by workflows.

Operations requiring this scope (4)
  • DELETE /api/v1/credentials/{credential_id}
  • POST /api/v1/credentials
  • POST /api/v1/credentials/{credential_id}/rotations
  • POST /api/v1/sms-inbox
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)
  • GET /api/v1/dashboard-agent/proposals/{run_id}
  • GET /api/v1/dashboard-agent/proposals/{run_id}/events
  • POST /api/v1/dashboard-agent/proposals
  • POST /api/v1/dashboard-agent/proposals/{run_id}/approvals/{operation_id}
  • POST /api/v1/dashboard-agent/proposals/{run_id}/cancel
Allowed Allowed Allowed
dashboards:read

Ask the governed dashboard agent to analyze organization workflow data.

Operations requiring this scope (1)
  • POST /api/v1/dashboard-agent/query
Allowed Allowed Allowed
executions:read

Read permitted workflow metadata, execution state and results.

Operations requiring this scope (10)
  • GET /api/v1/executions
  • GET /api/v1/executions/{execution_id}
  • GET /api/v1/executions/{execution_id}/phases
  • GET /api/v1/workflow-definitions
  • GET /api/v1/workflow-definitions/{workflow_definition_id}
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/logic
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/records
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/runs
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/versions
  • GET /api/v1/workflow-runs/{workflow_instance_id}/phases
Allowed Allowed Allowed
executions:write

Start approved agent and workflow executions and cancel individual workflow runs.

Operations requiring this scope (3)
  • POST /api/v1/installations/{installation_id}/executions
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/executions
  • POST /api/v1/workflow-runs/{workflow_instance_id}/cancel
Allowed Allowed Allowed
installations:read

Read installation state and connected sources.

Operations requiring this scope (5)
  • GET /api/v1/installations/{installation_id}
  • GET /api/v1/installations/{installation_id}/authorization-actions
  • GET /api/v1/installations/{installation_id}/source-batches/{batch_id}
  • GET /api/v1/installations/{installation_id}/sources
  • GET /api/v1/installations/{installation_id}/sources/{source_id}
Allowed Allowed Allowed
installations:write

Install agents and manage their sources and authorization actions.

Operations requiring this scope (11)
  • DELETE /api/v1/installations/{installation_id}
  • DELETE /api/v1/installations/{installation_id}/sources/{source_id}
  • POST /api/v1/agents/{agent_id}/installations
  • POST /api/v1/installations/{installation_id}/authorization-actions
  • POST /api/v1/installations/{installation_id}/provisioning-retries
  • POST /api/v1/installations/{installation_id}/source-batches
  • POST /api/v1/installations/{installation_id}/source-batches/{batch_id}/cancel
  • POST /api/v1/installations/{installation_id}/source-batches/{batch_id}/complete
  • POST /api/v1/installations/{installation_id}/source-batches/{batch_id}/upload-actions
  • POST /api/v1/installations/{installation_id}/sources
  • POST /api/v1/installations/{installation_id}/sources/{source_id}/complete
Allowed Allowed Allowed
integrations:connect

Attach encrypted credential references to integrations and manage connections.

Operations requiring this scope (4)
  • DELETE /api/v1/integrations/connections/{connection_id}
  • POST /api/v1/integrations/connections/{connection_id}/validate
  • POST /api/v1/integrations/{type_key}/authorizations
  • POST /api/v1/integrations/{type_key}/connections
Unavailable Allowed Allowed
integrations:generate

Use supplied API documentation to discover, generate, and validate an organization integration.

Operations requiring this scope (7)
  • POST /api/v1/integrations/factory/discoveries
  • POST /api/v1/integrations/factory/generations
  • POST /api/v1/integrations/factory/generations/{run_id}/capability-tests
  • POST /api/v1/integrations/factory/generations/{run_id}/validations
  • POST /api/v1/integrations/factory/uploads
  • POST /api/v1/integrations/factory/uploads/{upload_id}/complete
  • POST /api/v1/integrations/{type_key}/factory/discoveries
Unavailable Allowed Allowed
integrations:promote

Make a validated organization-owned integration live for workflow execution.

Operations requiring this scope (1)
  • POST /api/v1/integrations/factory/generations/{run_id}/promote
Unavailable Allowed Allowed
integrations:read

Browse integration definitions, capabilities, factory runs, and safe connection metadata.

Operations requiring this scope (10)
  • GET /api/v1/integrations
  • GET /api/v1/integrations/catalog
  • GET /api/v1/integrations/categories
  • GET /api/v1/integrations/connections
  • GET /api/v1/integrations/factory/discoveries/{run_id}
  • GET /api/v1/integrations/factory/discoveries/{run_id}/events
  • GET /api/v1/integrations/factory/generations/{run_id}
  • GET /api/v1/integrations/factory/generations/{run_id}/capability-tests/{test_id}
  • GET /api/v1/integrations/factory/generations/{run_id}/events
  • GET /api/v1/integrations/{type_key}
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)
  • GET /api/v1/logs
  • GET /api/v1/logs/summary
Allowed Allowed Allowed
metrics:read

Read Marketplace agent and installation metrics.

Operations requiring this scope (10)
  • GET /api/v1/agents/{agent_id}/metrics
  • GET /api/v1/agents/{agent_id}/metrics/dashboards
  • GET /api/v1/agents/{agent_id}/metrics/dashboards/{dashboard_id}
  • GET /api/v1/dashboards
  • GET /api/v1/dashboards/{dashboard_id}
  • GET /api/v1/installations/{installation_id}/metrics
  • GET /api/v1/installations/{installation_id}/metrics/dashboards
  • GET /api/v1/installations/{installation_id}/metrics/dashboards/{dashboard_id}
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/metrics/dashboards
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/metrics/dashboards/{dashboard_id}
Allowed Allowed Allowed
planner:control

Send keyboard and pointer input to a Planner browser session.

Operations requiring this scope (1)
  • POST /api/v1/planner/builds/{build_id}/steps/{step_number}/browser-session/control
Allowed Allowed Allowed
planner:export

Export the full reusable Planner build artifact.

Operations requiring this scope (1)
  • GET /api/v1/planner/builds/{build_id}/export
Allowed Allowed Allowed
planner:promote

Promote completed builds or save reusable templates.

Operations requiring this scope (6)
  • PATCH /api/v1/workflow-definitions/{workflow_definition_id}
  • POST /api/v1/planner/builds/{build_id}/promote
  • POST /api/v1/planner/builds/{build_id}/template
  • POST /api/v1/planner/workspaces/{session_id}/publications
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/archive
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/rollback
Unavailable Allowed Allowed
planner:read

List builds, durable state, and public build events.

Operations requiring this scope (6)
  • GET /api/v1/planner/builds
  • GET /api/v1/planner/builds/{build_id}
  • GET /api/v1/planner/builds/{build_id}/events
  • GET /api/v1/planner/workspaces
  • GET /api/v1/planner/workspaces/{session_id}
  • GET /api/v1/planner/workspaces/{session_id}/turns/{run_id}/events
Allowed Allowed Allowed
planner:view

Open the live noVNC view for a Planner browser step.

Operations requiring this scope (2)
  • GET /api/v1/planner/builds/{build_id}/steps/{step_number}/browser-session
  • POST /api/v1/planner/workspaces/{session_id}/live-view
Allowed Allowed Allowed
planner:write

Start, resume, test, accept, reject, and abandon Planner builds.

Operations requiring this scope (15)
  • POST /api/v1/browser/sessions/{session_id}/apply
  • POST /api/v1/planner/builds
  • POST /api/v1/planner/builds/{build_id}/abandon
  • POST /api/v1/planner/builds/{build_id}/plan/actions
  • POST /api/v1/planner/builds/{build_id}/resume
  • POST /api/v1/planner/builds/{build_id}/spec/answers
  • POST /api/v1/planner/builds/{build_id}/steps/{step_number}/actions
  • POST /api/v1/planner/builds/{build_id}/steps/{step_number}/assist
  • POST /api/v1/planner/builds/{build_id}/steps/{step_number}/cancel
  • POST /api/v1/planner/workflow-files
  • POST /api/v1/planner/workspaces
  • POST /api/v1/planner/workspaces/{session_id}/controls
  • POST /api/v1/planner/workspaces/{session_id}/internet-grant
  • POST /api/v1/planner/workspaces/{session_id}/messages
  • POST /api/v1/planner/workspaces/{session_id}/read-test-grant
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)
  • POST /api/v1/queue-designs/{session_id}/approve
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)
  • POST /api/v1/queue-designs/{session_id}/publish
  • POST /api/v1/queue-designs/{session_id}/rollback
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)
  • GET /api/v1/queue-designs
  • GET /api/v1/queue-designs/targets
  • GET /api/v1/queue-designs/{session_id}
  • GET /api/v1/queue-designs/{session_id}/events
  • GET /api/v1/queue-designs/{session_id}/versions
  • GET /api/v1/queue-designs/{session_id}/versions/{version_id}
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)
  • DELETE /api/v1/queue-designs/{session_id}/previews
  • POST /api/v1/queue-designs
  • POST /api/v1/queue-designs/{session_id}/cancel
  • POST /api/v1/queue-designs/{session_id}/messages
Allowed Allowed Allowed
recordings:read

Download the reusable recorder and read recordings created through this organization's recording invitations.

Operations requiring this scope (3)
  • GET /api/v1/recordings
  • GET /api/v1/recordings/extension
  • GET /api/v1/recordings/{recording_id}/download
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)
  • DELETE /api/v1/recordings/invitations/{invitation_id}
  • POST /api/v1/recordings/invitations
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)
  • GET /api/v1/review-items
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/records
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)
  • POST /api/v1/review-items/decisions
Allowed Allowed Allowed
schedules:read

List organization workflow schedules and their recent runs.

Operations requiring this scope (2)
  • GET /api/v1/schedules
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/schedule
Allowed Allowed Allowed
schedules:write

Create, update, pause, resume, trigger, and delete workflow schedules.

Operations requiring this scope (6)
  • DELETE /api/v1/workflow-definitions/{workflow_definition_id}/schedule
  • PATCH /api/v1/workflow-definitions/{workflow_definition_id}/schedule
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/schedule
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/schedule/pause
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/schedule/resume
  • POST /api/v1/workflow-definitions/{workflow_definition_id}/schedule/trigger
Allowed Allowed Allowed
sessions:read

Read coordinated session state and replayable events. Queue designs also require queue_ui:read.

Operations requiring this scope (5)
  • GET /api/v1/sessions/{session_id}
  • GET /api/v1/sessions/{session_id}/events
  • GET /api/v1/sessions/{session_id}/live-frame
  • GET /api/v1/sessions/{session_id}/live-status
  • POST /api/v1/sessions/{session_id}/live-stream
Allowed Allowed Allowed
sessions:write

Send attributed session messages. Queue designs also require queue_ui:write.

Operations requiring this scope (1)
  • POST /api/v1/sessions/{session_id}/messages
Allowed Allowed Allowed
sms:read

Read message bodies delivered to this organization's dedicated VoIP inbox.

Operations requiring this scope (1)
  • GET /api/v1/sms-inbox/messages
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)
  • GET /api/v1/usage
  • GET /api/v1/usage/planner
  • GET /api/v1/workflow-definitions/{workflow_definition_id}/operating-cost
Allowed Allowed Allowed
webhooks:read

Read organization webhook subscriptions and delivery history.

Operations requiring this scope (5)
  • GET /api/v1/webhook-deliveries
  • GET /api/v1/webhook-deliveries/{delivery_id}
  • GET /api/v1/webhooks
  • GET /api/v1/webhooks/configuration
  • GET /api/v1/webhooks/{subscription_id}
Allowed Allowed Allowed
webhooks:write

Create, test, change, delete, rotate, and redeliver organization webhooks.

Operations requiring this scope (6)
  • DELETE /api/v1/webhooks/{subscription_id}
  • PATCH /api/v1/webhooks/{subscription_id}
  • POST /api/v1/webhook-deliveries/{delivery_id}/redeliver
  • POST /api/v1/webhooks
  • POST /api/v1/webhooks/{subscription_id}/rotate-secret
  • POST /api/v1/webhooks/{subscription_id}/test
Allowed Allowed Allowed