Skip to main content

​
API Key Authentication

All Refine API endpoints require authentication using an API key. Include your API key in the request headers: 
REFINE_API_KEY: your_api_key_here
Keep your API key secure and never expose it in client-side code or public repositories.

​
API Key Types

Refine API keys come with different permission levels:
Full access to resources within your organization. Can manage catalogs, products, and access all API endpoints for your organization.
Read access to resources within your organization. Can search products and get recommendations but cannot modify catalogs or products.

​
Authorization Rules

Different endpoints have different authorization requirements. All access is limited to resources within your organization:
Endpoint TypeADMINUSER
Catalog Management✓✗
Product Management✓✗
Search✓✓
Recommendations✓✓
All API keys can only access resources within their own organization. You cannot access another organization’s catalogs or products.

​
Error Responses

Authentication failures will return appropriate HTTP status codes:

​
401 Unauthorized

Returned when:
  • REFINE_API_KEY header is missing
  • API key is invalid
  • Organization is inactive
  • Rate limit grace period has expired
{
  "status": 401,
  "message": "Unauthorized",
  "time": "2024-06-14T19:21:00Z",
  "method": "GET",
  "url": "/organizations/a8cd2722-1234-4567-9abc-def123456789/catalogs"
}

​
403 Forbidden

Returned when:
  • API key doesn’t have permission for the requested resource
  • Attempting to access resources from a different organization
{
  "status": 403,
  "message": "Forbidden",
  "time": "2024-06-14T19:21:00Z",
  "method": "POST",
  "url": "/organizations/a8cd2722-1234-4567-9abc-def123456789/catalogs"
}

​
Best Practices

Rotate Keys Regularly

Rotate your API keys periodically to maintain security

Use Environment Variables

Store API keys in environment variables, not in code

Restrict Key Permissions

Use the minimum permission level required for your use case

Monitor Usage

Track API key usage to detect any unusual activity
⌘I