Authentication

The Storefront API uses two layers of authentication: a Storefront API key that identifies your store on every request, and optional customer tokens (JWTs) for endpoints that act on behalf of a logged-in customer.

Storefront API key

Every request must include your Storefront API key in the X-Api-Key header:

curl "https://api.opencals.com/storefront/products" \
  -H "X-Api-Key: sfk_your_key_here"

Keys are created in the dashboard under Settings → API Keys, are scoped to a single store, and start with sfk_.

Treat the key like a secret: keep it in server-side environment variables and proxy requests through your own backend rather than calling the API directly from the browser.

Customer authentication

Endpoints that read or modify a specific customer’s data — their appointments, orders, and profile — additionally require a customer access token as a Bearer token:

Authorization: Bearer <customer_access_token>
X-Api-Key: sfk_your_key_here

Exchange a customer’s credentials for a token pair:

curl -X POST "https://api.opencals.com/storefront/auth/sign-in" \
  -H "X-Api-Key: sfk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "password": "securepassword"
  }'

{
  "accessToken": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…"
}

Refresh tokens

Access tokens expire. Get a fresh pair by calling the refresh endpoint with the refresh token as the Bearer token:

curl "https://api.opencals.com/storefront/auth/refresh" \
  -H "X-Api-Key: sfk_your_key_here" \
  -H "Authorization: Bearer <customer_refresh_token>"

All auth endpoints

Method	Endpoint	Description
`POST`	`/storefront/auth/sign-up`	Register a new customer (sends a verification email)
`POST`	`/storefront/auth/sign-in`	Sign in with email and password
`POST`	`/storefront/auth/oauth`	Sign in or register via an OAuth provider
`GET`	`/storefront/auth/refresh`	Refresh tokens (pass the refresh token as Bearer)
`POST`	`/storefront/auth/request-email-verification`	Resend the verification email
`POST`	`/storefront/auth/verify-email`	Verify an email with the emailed token
`POST`	`/storefront/auth/request-password-reset`	Send a password reset email
`POST`	`/storefront/auth/reset-password`	Reset a password with the emailed token

See the API reference for full request and response shapes.

Which endpoints need a customer token?

Customer-scoped endpoints — appointments, orders, and self-service profile management — require a customer Bearer token. Catalog endpoints (products, availability, staff members, locations, collections, store settings) need only the API key.

Cart and checkout endpoints accept an optional customer token: guests can book without an account, and checkout can return auth tokens for new customers so they’re signed in automatically after their first booking.

Error responses

Errors use conventional HTTP status codes with a JSON body:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    { "property": "email", "messages": ["Email is required"] }
  ]
}

Status	Meaning
`400`	Validation error — check the `errors` array for per-field details
`401`	Invalid or missing API key or customer token
`404`	Resource not found
`429`	Rate limit exceeded — see rate limits

Security checklist

Store sfk_ keys in environment variables, never in client bundles or repositories.
Call the Storefront API from your server (API routes, server components, edge functions) and keep the key out of browser network requests.
Store customer refresh tokens in httpOnly cookies rather than localStorage where possible.
Rotate API keys from the dashboard if a key is ever exposed.

Get started

Guides

Storefront API key

Customer authentication

Refresh tokens

All auth endpoints

Which endpoints need a customer token?

Error responses

Security checklist

​Storefront API key

​Customer authentication

​Sign in

​Refresh tokens

​All auth endpoints

​Which endpoints need a customer token?

​Error responses

​Security checklist

Storefront API key

Customer authentication

Sign in

Refresh tokens

All auth endpoints

Which endpoints need a customer token?

Error responses

Security checklist