Authentication

The REST API uses API key authentication via the Authorization header.

Creating an API key

Open the SimplerSuite Access dashboard in your Shopify admin
Go to Settings → API Keys
Click Create API Key
Select the scopes you need
Copy the API Key — it is only shown once

API keys use the format eh_live_* (production) or eh_test_* (test mode).

Using the API key

Pass the key in the Authorization header on all API requests:

curl -H "Authorization: Bearer eh_live_abc123..." \
  https://api.simplersuite.co/v1/entitlements?customer_id=cust_123

Base URL

All API endpoints are relative to:

https://api.simplersuite.co/v1

Scopes

Each API key is granted specific scopes that control what it can access:

Scope	Description
`entitlements:read`	Read entitlements and check access
`entitlements:write`	Create, update, revoke, suspend, reactivate entitlements
`products:read`	List and get products
`products:write`	Create and update products
`customers:read`	List customer entitlements and downloads
`webhooks:manage`	Manage webhook endpoints
`events:read`	Read event logs
`files:read`	Generate download URLs
`files:write`	Generate upload URLs, confirm uploads

Rate limits

Endpoint type	Limit
Read endpoints	120 requests/minute per API key
Write endpoints	60 requests/minute per API key

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Response format

All successful responses use this envelope:

{
  "data": { },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-01T12:00:00.000Z"
  }
}

Paginated responses add:

{
  "pagination": {
    "total": 42,
    "limit": 25,
    "has_more": true,
    "next_cursor": "eyJ..."
  }
}

Error format

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "INVALID_API_KEY",
    "request_id": "req_abc123"
  }
}

Status	Meaning
`400`	Validation error or bad request
`401`	Authentication failed
`402`	Billing/quota limit reached
`403`	Insufficient scope
`404`	Resource not found
`409`	Conflict (invalid status transition)
`429`	Rate limited
`500`	Internal server error