Easel

← API Documentation

Authentication

The Easel API uses Bearer token authentication with API keys. All requests must include a valid API key in the Authorization header.

Authentication Flow

  1. Obtain an API key from your store's admin panel
  2. Include the API key in the Authorization header of every request
  3. The API validates the key and checks permissions for the requested operation

API Key Format

API keys are Bearer tokens that must be included in the Authorization header:

Authorization: Bearer your_api_key_here

Permissions

API keys have different permission levels that control what operations they can perform:

Read Permission

  • Can perform GET requests to retrieve data
  • Cannot create, update, or delete resources

Write Permission

  • Can perform GET, POST, PUT requests
  • Can create, update, and retrieve resources
  • Cannot delete resources (except where specifically allowed)

Admin Permission

  • Full access to all operations
  • Can perform GET, POST, PUT, DELETE requests

Request Headers

All authenticated requests must include:

Authorization: Bearer your_api_key_here
Content-Type: application/json

Authentication Errors

Missing Authorization Header

Status: 401 Unauthorized

{
  "error": "Authorization header is required",
  "code": "MISSING_AUTHORIZATION"
}

Invalid Authorization Format

Status: 401 Unauthorized

{
  "error": "Authorization header must be 'Bearer <token>'",
  "code": "INVALID_AUTHORIZATION"
}

Empty API Key

Status: 401 Unauthorized

{
  "error": "API key cannot be empty",
  "code": "EMPTY_TOKEN"
}

Invalid API Key

Status: 401 Unauthorized

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Authentication Service Error

Status: 500 Internal Server Error

{
  "error": "Failed to authenticate API key",
  "code": "AUTHENTICATION_ERROR"
}

Permission Errors

Insufficient Permissions

Status: 403 Forbidden

{
  "error": "API key does not have write permissions",
  "code": "INSUFFICIENT_PERMISSIONS"
}

Method Not Allowed

Status: 405 Method Not Allowed

{
  "error": "HTTP method not allowed",
  "code": "METHOD_NOT_ALLOWED"
}

Store Not Found

Status: 401 Unauthorized

{
  "error": "Store not found",
  "code": "STORE_NOT_FOUND"
}

Store Lookup Error

Status: 500 Internal Server Error

{
  "error": "Failed to lookup store",
  "code": "STORE_LOOKUP_ERROR"
}

Store Locked

Status: 403 Forbidden

{
  "error": "Store is locked",
  "code": "STORE_LOCKED"
}

Rate Limiting

API requests are rate limited per store. When rate limits are exceeded:

Status: 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED"
}

Rate Limit Headers

All authenticated requests include rate limit information in the response headers:

X-Ratelimit-Limit: 1000
X-Ratelimit-Remaining: 999
X-Ratelimit-Reset: 1672531200
  • X-Ratelimit-Limit: Maximum requests allowed per time window
  • X-Ratelimit-Remaining: Requests remaining in current window
  • X-Ratelimit-Reset: Unix timestamp when the rate limit resets

Rate Limit Service Error

Status: 500 Internal Server Error

{
  "error": "Failed to check rate limit",
  "code": "RATE_LIMIT_ERROR"
}

Example Authenticated Request

curl -X GET "https://studio.easel.engineering/api/v1/products" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Security Best Practices

  1. Keep API keys secure - Never expose API keys in client-side code or public repositories
  2. Use HTTPS - All API requests should be made over HTTPS
  3. Rotate keys regularly - Generate new API keys periodically
  4. Use appropriate permissions - Grant the minimum permission level required for your use case
  5. Monitor usage - Keep track of API key usage and watch for unusual activity