Authentication

All requests to the Umbrella API require authentication. There are two methods depending on the endpoint.

Shopify header authentication

Public-facing endpoints (widget data, claims, policy lookups) authenticate using Shopify shop domain headers:

X-Shopify-Shop-Domain: your-store.myshopify.com
X-Shopify-Customer-Id: 1234567890

When you install the Umbrella Shopify app, your shop domain is automatically registered. No manual setup is needed for storefront endpoints.

Internal API key authentication

Server-side endpoints (eligibility assessment, product sync) authenticate with an API key in the request body:

{
  "internalApiKey": "your-internal-api-key",
  "orgId": "your-org-id"
}

To generate or rotate an internal API key:

1. Go to Dashboard > Settings > Integrations
2. Locate the API Keys section
3. Click Generate New Key or Rotate Key

Rotating a key immediately invalidates the previous one. Update all integrations before rotating.

Test vs live environments

Test-mode requests return "testingMode": true in responses and use sample warranty data.

Error handling

Common error status codes across all endpoints:

When you receive a 429 response, wait for the retry period before sending more requests. Implement exponential backoff for high-volume scenarios.

Related

• Endpoints Overview — Full list of available endpoints
• Warranty API — Warranty plan management endpoints
• Webhooks Reference — Event-driven integrations