Authentication

All requests to the Decal API require a secret API key passed in the Authorization header:

Authorization: Bearer sk_live_your_api_key_here

Getting your API keys

API keys are available in the Decal Dashboard under Settings > API Keys. You'll have separate keys for test and live mode.

Key format

Each API key is scoped to a specific organization and a specific mode. A key from one organization cannot access another organization's data, and a test key cannot access live resources or vice versa. The key prefix encodes the mode — every resource created or accessed with a sk_live_ key is a live resource; every resource touched by a sk_test_ key is a test resource.

Test vs live mode

Use your sk_test_ key during development and integration testing. Test resources:

• Behave identically to live resources in the API
• Do not process real payments — sandbox payment methods are supported
• Are fully isolated from live data — a sk_live_ key cannot access test resources, and vice versa
• Return test-mode data and IDs (e.g. cs_test_..., ord_test_..., cust_test_...)

Switch to your sk_live_ key when you're ready to accept real payments in production.

Using the API key

Include the key in every request:

curl https://api.usedecal.com/v0/orders \
  -H "Authorization: Bearer sk_live_your_api_key_here"

const response = await fetch("https://api.usedecal.com/v0/orders", {
  headers: {
    Authorization: "Bearer sk_live_your_api_key_here",
  },
});

Keep your secret API key out of client-side code. All Decal API calls should originate from your server.

Authentication errors

Authentication failures use the standard error response shape.

Mode mismatches (e.g. using a sk_test_ key to access a cs_live_* resource) return 404 rather than 403 — the resource is not visible to that key. See Errors for the full response shape, the list of HTTP status codes, and how to use errorId for support.