Security & credentials

Get a Shop ID

Mint a keyless sandbox Shop ID in a single API call, use it immediately, and hand it to a human to claim and set up payouts.

Mint a sandbox shop

A Shop ID is the publishable identifier behind every mockup, buy link, and render — public, like a Cloudinary cloud name. You don’t need an account to get one: a single unauthenticated POST /shops/sandbox mints a working sandbox shop with no signup and no API key.

bash

# Mint a Shop ID in one call — no signup, no API key required.
curl -X POST https://api.snowcone.app/shops/sandbox -H 'Content-Type: application/json' -d '{}'
# → {
#   "shop_id": "ab3dPq7Rms",     # use as &shop= right away
#   "shop_secret": "scsec_…",     # for SIGNING image URLs (not an sk_ key)
#   "api_key": "kQ7r…2Fb",        # shop-scoped key, returned ONCE — Bearer it on the AI-gen /
#                                 # asset-write endpoints so generated art lands in THIS shop's
#                                 # bucket (revoked automatically once claimed)
#   "api_key_scopes": ["ai:generate", "ai:bg-remove", "uploads:write", "mockups"],
#   "claim": {                    # everything needed to drive the claim flow:
#     "user_code": "WXYZ-1234",                                              # human enters this at /activate
#     "verification_uri": "https://snowcone.app/activate",                   # where they go
#     "verification_uri_complete": "https://snowcone.app/activate?code=WXYZ-1234", # …with the code prefilled
#     "claim_token": "…",          # poll with this: GET /shops/claim, Authorization: Bearer <claim_token>
#     "expires_in": 86400          # seconds until the claim (and unclaimed shop) expires — 24h
#   }
# }

Building with an AI agent? Mint your own Shop ID, drop it into your URLs right away, and hand your human the verification_uri_complete to claim the shop and set up payouts whenever they’re ready. Sales work immediately and route to their account once claimed.

The scsec_… shop secret is for signing image URLs (see Signed URLs) — it is not an sk_ secret API key and does not authorize a realtime grant. See Authentication for every credential type side by side.

Use the Shop ID

Drop the shop_id straight into any mockup or buy URL as &shop=. That’s the whole quickstart — Get started walks the full render → product info → buy flow. Mint once and reuse the Shop ID; don’t ship one copied from the docs or our demos — those attribute sales to someone else.

Claim it (human, payouts)

A sandbox shop is unclaimed until a human binds it to their account, and it lives 24 hours unclaimed. Send them to verification_uri_complete — e.g. https://snowcone.app/activate?code=WXYZ-1234 — where they log in, confirm the code, and set up payouts. Poll GET /shops/claim with the claim_token to watch the status flip to claimed.

bash

# Watch the claim status flip to "claimed" after your human sets up payouts.
curl https://api.snowcone.app/shops/claim -H 'Authorization: Bearer <claim_token>'

What changes at claim. The shop re-parents to the human’s organization and stops being a sandbox — same Shop ID, so every mockup and buy URL keeps working. But the credentials the agent was minted with stop working: the scsec_… shop secret is rotated (the fresh one is shown once to the claimer) and the sandbox api_key is revoked. The asset allowlist also locks down to the shop’s own storage origin unless it was already customized. After claim, the human holds the keys — they mint their own sk_ keys at snowcone.app/studio/api-keys and can re-grant the agent least-privilege scopes.

See the full device-flow walkthrough on Authentication and every endpoint on the API reference.

Limits & lifecycle

Minting is rate-limited per IP — 60/hour and 200 unclaimed shops. Over either limit returns 429 resource_exhausted, so mint once and reuse rather than minting per attempt. Done with a sandbox shop? Release it (unclaimed shops only) to free your budget:

bash

# Done with a sandbox shop? Release it (unclaimed shops only) to free your
# per-IP mint budget. Authorize with the scsec_ shop secret from the mint.
curl -X DELETE https://api.snowcone.app/shops/sandbox/ab3dPq7Rms \
  -H 'Authorization: Bearer scsec_…'