Authentication

Every request to the Hydra API requires an API key passed in the Authorization header.

curl https://api.hydrajs.dev/v1/products \
  -H "Authorization: Bearer sk_your_api_key"

API keys

When you create a project, you receive two keys:

Prefix	Type	Usage
sk_	Secret	Full CRUD, server-side only
pk_	Publishable	Read-only + cart/checkout, client-safe

Each key is 35 characters: a 3-character prefix followed by 32 random alphanumeric characters.

Keys are shown once at creation time. Store them somewhere secure. They cannot be retrieved later.

Secret vs publishable

Secret keys (sk_*) have full access to every endpoint. Use them in server-side code only. Never expose them in a browser, mobile app, or client-side bundle.

Publishable keys (pk_*) are safe to use in client-side code. They can:

• Read products, collections, and shipping rates
• Create and manage carts
• Create checkouts
• Query search

They cannot create, update, or delete resources like products, orders, or webhooks. Attempting a write operation with a publishable key returns a 403:

{
	"error": {
		"code": "forbidden",
		"message": "Key does not have permission for this action."
	}
}

Error responses

Missing or invalid key

Status 401:

{
	"error": {
		"code": "unauthorized",
		"message": "Missing or invalid API key."
	}
}

Insufficient permissions

Status 403 (e.g., publishable key on a write endpoint):

{
	"error": {
		"code": "forbidden",
		"message": "Key does not have permission for this action."
	}
}

Rate limits

Requests are rate-limited per project using a sliding window.

Plan	Requests per minute
Free	60
Pro	600

Every response includes rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1692374520

When the limit is exceeded, the API returns a 429 with a Retry-After header:

{
	"error": {
		"code": "rate_limited",
		"message": "Too many requests."
	}
}

Monthly quota

Each plan includes a monthly request quota. When exceeded, the API returns a 429:

{
	"error": {
		"code": "quota_exceeded",
		"message": "Monthly API quota exceeded."
	}
}

Plan	Monthly quota
Free	2,000
Pro	100,000

A usage.warning webhook event fires at 80%, 90%, and 100% of your quota.

CORS

CORS headers are applied only to requests made with publishable keys — secret keys are server-side only and don’t need CORS.

To allow browser requests from your storefront, add your domain(s) to Allowed Origins in your project settings (or via the Store API). Only exact-match origins are accepted:

https://mystore.com
https://staging.mystore.com

Set a single * entry to allow requests from any origin. When * is configured, the API reflects the actual Origin header back in Access-Control-Allow-Origin (rather than sending a literal *), which is compatible with credentialed requests.

If the requesting origin is not in the allowed list, no CORS headers are returned and the browser blocks the response.

Allowed methods and headers

Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-API-Key

Preflight

The API handles OPTIONS requests before authentication, so preflight checks succeed without an API key.

---

Best practices

• Never commit keys to version control. Use environment variables.
• Use publishable keys on the client. Secret keys belong on the server.
• Monitor lastUsedAt. Identify and remove unused keys.