Authentication

The Storefront API uses two layers of authentication: an 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.

API keys

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

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

Keys are created in the dashboard under Users → your user → API Keys and are scoped to a single store. Pick the kind by where your code runs:

Key	Prefix	Use it in	Restrict it with
Private storefront key	`spk_`	Server code: Next.js server components and API routes, serverless functions, your backend	Optional allowed server IPs
Public storefront key	`sfk_`	Browser code: embedded widgets, client-side apps	Allowed origins (your domains)

Both work with every storefront endpoint. Admin keys (sk_) are for admin integrations such as Zapier and aren’t accepted by the storefront API.

Private keys are secrets: keep them in server-side environment variables. The API doesn’t block them in a browser, so you can test from anywhere, but anyone who can read your browser code can use the key. A public key is visible to anyone who opens your site, so restrict it to your domains with allowed origins.

Forward the buyer’s IP

When your server calls the API for its visitors, every request comes from your server’s IP. Rate limits and sign-up, login and email protection then can’t tell your visitors apart. With a private key, send each visitor’s IP in X-Opencals-Buyer-Ip, and the API counts per buyer instead:

curl -X POST "https://api.opencals.com/storefront/auth/request-login-code" \
  -H "X-Api-Key: spk_your_key_here" \
  -H "X-Opencals-Buyer-Ip: 203.0.113.7" \
  -H "Content-Type: application/json" \
  -d '{ "email": "customer@example.com" }'

The header is optional, and it’s ignored with a public key and on requests sent from a browser. Take the IP from the header your host sets (for example x-real-ip or the first x-forwarded-for entry on Vercel), never from the request body. With the SDK, use the buyerIp option.

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. Checkout never returns tokens for an existing customer identified only by the email in the request; that customer signs in themselves to see the 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

Use a private key (spk_) on your server and keep it in environment variables, never in client bundles or repositories.
Forward the buyer’s IP (X-Opencals-Buyer-Ip) from your server so each visitor gets their own rate limits.
If your server has fixed outgoing IPs, add them to the private key’s allowed IPs.
Use a public key (sfk_) only in browser code, and set its allowed origins to your domains.
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

API keys

Forward the buyer’s IP

Customer authentication

Refresh tokens

All auth endpoints

Which endpoints need a customer token?

Error responses

Security checklist

​API keys

​Forward the buyer’s IP

​Customer authentication

​Sign in

​Refresh tokens

​All auth endpoints

​Which endpoints need a customer token?

​Error responses

​Security checklist

API keys

Forward the buyer’s IP

Customer authentication

Sign in

Refresh tokens

All auth endpoints

Which endpoints need a customer token?

Error responses

Security checklist