Authentication

The Gateway accepts two credential types. Pick by caller.

Service-account keys (recommended for agents)

A key is a string shaped sq_agt_<random>. Send it on every request:

-H "X-Agent-Key: sq_agt_xxx"
# or, equivalently:
-H "Authorization: Bearer sq_agt_xxx"

Keys are:

Scoped — carry only the scopes you grant.
Tenant-bound — locked to a merchant (and optionally specific stores).
Hashed at rest — only a SHA-256 hash is stored; the plaintext is shown once.
Rotatable & revocable — rotate (POST /keys/{id}/rotate) or revoke (DELETE /keys/{id}) anytime.
Rate-limited — per-key, with an optional per-key override.

If a key is bound to multiple stores, pass X-Store-ID: <store_id> to choose one.

Managing keys

Method	Path	Scope
`POST`	`/keys`	`agent:admin`
`GET`	`/keys`	`agent:admin`
`POST`	`/keys/{id}/rotate`	`agent:admin`
`DELETE`	`/keys/{id}`	`agent:admin`

curl -X POST https://api.platformdtc.com/api/v1/agent/v1/keys \
  -H "X-Agent-Key: sq_agt_admin" -H "Content-Type: application/json" \
  -d '{
    "name": "ads-bot",
    "scopes": ["ads:read","ads:write","analytics:read"],
    "store_ids": ["store_123"],
    "rate_limit_per_min": 240,
    "requires_approval": true,
    "expires_at": "2027-01-01T00:00:00Z"
  }'

User JWT (interactive / embedded)

A logged-in dashboard user’s JWT also authenticates the Gateway and acts as that user with full scope — convenient for embedded/interactive agents. The dashboard’s Agent Access pages use this.

-H "Authorization: Bearer <user_jwt>"

Prefer service-account keys for autonomous agents: they are least-privilege, independently revocable, rate-limited per agent, and produce a clean per-agent audit trail.

Headers at a glance

Header	When	Purpose
`X-Agent-Key` / `Authorization`	always	credential
`Idempotency-Key`	every non-GET	safe retries — see Idempotency
`X-Store-ID`	multi-store keys	target store

Overview

Merchant guides

Fundamentals

Service-account keys (recommended for agents)

Managing keys

User JWT (interactive / embedded)

Headers at a glance

​Service-account keys (recommended for agents)

​Managing keys

​User JWT (interactive / embedded)

​Headers at a glance

Service-account keys (recommended for agents)

Managing keys

User JWT (interactive / embedded)

Headers at a glance