Getting started

A PlatformDTC app is a third-party integration that a merchant installs to let your service act on their store through the Agent Gateway. Installing an app mints a scoped sq_agt_* token bound to that merchant — the same credential agents use — so everything in these docs (scopes, jobs, idempotency, webhooks) applies to apps unchanged.

App types

Type	What it is	Availability
`api`	A backend service that calls the Gateway with the installed token.	Phase 1 — available now
`embedded`	A UI that runs inside the merchant dashboard in an origin-locked iframe.	Phase 2
`skill`	A `SKILL.md` agent installed into the merchant’s runtime.	Phase 4

Phase 1 ships api apps via custom distribution — you share an install link directly with merchants you onboard. The public marketplace (apps.platformdtc.com) and one-click install arrive in Phase 2. Everything below is live today.

Become a partner

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/signup \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Integrations","contact_email":"[email protected]"}'
# -> { "data": { "id":"…", "slug":"acme-integrations", "status":"approved" } }

Confirm your partner profile any time with GET /appstore/partner/me.

An account linked to a partner can never be a reviewer — the two roles are mutually exclusive by design, so your team’s review of your own app is impossible.

Create an app

Creating an app returns its OAuth credentials. The client_secret is shown only once — store it in a secret manager immediately.

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/apps \
  -H "Authorization: Bearer $USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Loyalty",
    "app_type": "api",
    "redirect_uris": ["https://acme.example/oauth/callback"],
    "webhook_endpoint_url": "https://acme.example/hooks/platformdtc"
  }'
# -> { "data": {
#        "id": "app_…",
#        "client_id": "sq_app_…",
#        "client_secret": "<shown once>",
#        "status": "draft"
#      } }

Field	Notes
`client_id`	Public identifier (`sq_app_*`). Safe to embed in your authorize URLs.
`client_secret`	Secret. Verifies the token exchange and signs your webhooks. Never ship it to a browser.
`redirect_uris`	Exact-match allowlist. The authorize `redirect_uri` must match one of these byte-for-byte.
`webhook_endpoint_url`	Where declared webhook topics are delivered.

A new app starts in draft. Before a merchant can install it you submit a version for review; an approved version’s scopes are what installs may grant.

Rotating the client secret

Rotate the secret whenever you suspect exposure. Rotation returns a fresh secret once and keeps the previous one valid for a 72-hour grace window, so an in-flight integration never breaks mid-deploy.

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/apps/app_123/rotate-secret \
  -H "Authorization: Bearer $USER_JWT"
# -> { "data": { "client_secret": "<new — shown once>", "secret_rotated_at": "2026-07-23T12:00:00Z" } }

During the 72 hours after secret_rotated_at, both the new and previous secret verify token exchanges and validate webhook signatures. Roll the new secret out everywhere within the window; after it, only the new secret works.

Treat the client_secret like a password. It is the only proof that a token exchange or a webhook came from you. If it leaks, rotate immediately and complete the migration inside the 72-hour grace.

Install flow (OAuth)

Authorize, exchange, and use the token.

Webhooks

Subscribe to events and verify signatures.

Versions & review

Submit scopes and pass review.

Scopes

What each scope grants.

Build an App

App types

Become a partner

Create an app

Rotating the client secret

Next

Install flow (OAuth)

Webhooks

Versions & review

Scopes

​App types

​Become a partner

​Create an app

​Rotating the client secret

​Next

Install flow (OAuth)

Webhooks

Versions & review

Scopes

App types

Become a partner

Create an app

Rotating the client secret

Next