Scopes and approvals - PlatformDTC

Theme scopes

Scope	Grants
`read_themes`	List and get themes, the manifest, file reads, versions, theme check, preview links, publish status
`write_themes`	Create and delete development themes, write and delete files, roll back to a version
`publish_themes`	Publish a theme as the live theme — subject to the store’s approval setting · spend

Scopes are checked exactly: write_themes does not imply read_themes, so an agent that edits themes needs both. Theme check and preview are read_themes so a reviewer key can run them without being able to change anything. OAuth tokens carry the scopes the merchant ticked on the consent screen, for one store. Static sq_agt_* keys carry the scopes chosen when the key was created under Agents → Access → API keys. Tokens issued to third-party apps are never widened by a super-scope: a token grants its listed scopes and nothing else.

Grant publish_themes only where you want the agent to ask to publish. An agent with read_themes and write_themes can build, check and preview a development theme, and hand you a preview link — you publish from the dashboard.

Publishing and approval

publish_themes is a spend-class scope: publishing changes what every customer sees. Whether a publish waits for a person is a store setting, agent_theme_publish_policy, set in the dashboard under Settings → Developer → Build with your agent → Agent theme publishing:

Setting	Value	What happens when an agent publishes
Require my approval (default)	`approval_required`	The publish is parked as a job in `pending_approval`. Nothing changes on the live store until it is approved.
Publish automatically	`auto`	The publish is queued straight away.

Either way the call returns 202:

{ "success": true, "data": { "job_id": "…", "status": "pending_approval" } }

Approving

The merchant approves or denies it in Settings → Developer → Build with your agent → Theme publish approvals (Approve & publish or Deny). An integration holding agent:admin can resolve it through the API instead:

curl -X POST https://api.platformdtc.com/api/v1/agent/v1/approvals/$JOB_ID/resolve \
  -H "Authorization: Bearer sq_agt_admin_key" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve"}'

On approval the job runs the publish. See Human approval gate for the approval lifecycle shared by every spend action.

What a publish does

A theme publish is the same publish the dashboard runs:

Theme check runs in publish mode. Any error returns 422 CHECK_FAILED with the full result, and nothing is published or parked for approval.
The theme becomes the live (main) theme, the storefront is deployed, and the search-engine bake runs.
The webhook theme.published fires on success, or theme.publish_failed on failure.

Publishes for one store run one at a time. Track progress with GET /themes/{id}/publish-status (the get_publish_status tool).

What the agent should do with `pending_approval`

Tell the person it is waiting for their approval, and stop. Do not call publish again while it waits. Poll get_publish_status, or subscribe to the theme.published webhook.

Audit

Every theme call — reads included — is written to the agent audit log with the key that made it. Every successful write batch is recorded as a theme version whose author is agent:<key name>, so a version from an OAuth connection reads agent:OAuth: <client name>.

​Theme scopes

​Publishing and approval

​Approving

​What a publish does

​What the agent should do with pending_approval

​Audit

Theme scopes

Publishing and approval

Approving

What a publish does

What the agent should do with `pending_approval`

Audit