Authentication
Merchant API keys, scopes, and how to send them.
API keys
Create keys in the Swop web app at Dashboard → Developer. Each key has:
| Format | Notes | |
|---|---|---|
| Key ID | mk_… | Safe to log and show |
| Secret | swop_sk_… | Shown once at creation. Swop stores only a hash and can't show it again. |
Keys are server credentials. Keep the secret in an environment variable on your server. Never put it in browser JavaScript, a mobile app or a public repository. If a key leaks, revoke it in the Developer page and create a new one.
Sending the key
Use either header:
curl https://apps.apiswop.co/api/v5/merchant/me \
-H "Authorization: Bearer $SWOP_MERCHANT_KEY"Scopes
A key can do only what its scopes allow. Tick the fewest you need.
| Scope | Lets the key… |
|---|---|
profile.read | Read your public profile |
commerce.read | Read your products, orders and checkouts |
commerce.checkout | Create checkouts from a cart. The only scope that can lead to money moving. |
commerce.embed | Mint embed tokens so a registered website can frame your checkout |
commerce.card | Offer card payments. Active only while your account is verified for card. |
commerce.write | Reserved for creating and editing products |
drops.read | Read your locations and terminals |
drops.write | Reserved for editing locations and drops |
Granted vs. effective scopes
Granted scopes are what you ticked. Effective scopes are what the key can do right now. They differ in one case: commerce.card only becomes effective while your account is verified for card. If verification lapses, or can't be checked, the key keeps working for everything else and simply can't offer card. GET /me shows the effective scopes.
Failures
| Status | Meaning |
|---|---|
401 | No key, unknown key, or revoked key. Every case returns the same message, so keys can't be probed. |
403 | Valid key, missing scope. The body names the scope and lists grantedScopes and effectiveScopes. |
403 with code: "ACCOUNT_FLAGGED" | The account is restricted. Contact support. |
{
"success": false,
"state": "failed",
"message": "This key does not have the \"commerce.card\" scope right now.",
"hint": "Card requires completing merchant verification. Crypto checkout does not.",
"grantedScopes": ["commerce.read", "commerce.checkout", "commerce.card"],
"effectiveScopes": ["commerce.read", "commerce.checkout"]
}