Authentication
CarphaCom uses three auth surfaces:
1. Admin: Bearer JWT
Admin endpoints (/admin/*) require a Bearer JWT in the Authorization header.
Obtain a token
curl -X POST https://shop.example.com/auth/user/emailpass \
-H "Content-Type: application/json" \
-d '{"email":"admin@yourshop.com","password":"YourPassword"}'
Response:
{ "token": "eyJhbGciOiJIUzI1NiIs..." }
Use it:
curl https://shop.example.com/admin/products \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Tokens expire after 24 hours by default. Re-authenticate or implement a refresh flow.
Cookie-based admin auth (admin-panel)
The bundled admin panel uses cookies, not Bearer headers. After login, it stores
medusa_token (HTTP-only) and a custom admin_session (HTTP-only). The admin's proxy
routes automatically convert these to Bearer headers when calling /admin/* endpoints.
2. Store: Publishable key
Store endpoints (/store/*) require a publishable API key in the x-publishable-api-key
header.
Obtain a publishable key
curl https://shop.example.com/admin/publishable-api-keys \
-H "Authorization: Bearer $TOKEN"
Or in admin: Settings → API key management → Publishable keys.
Use it
curl https://shop.example.com/store/products \
-H "x-publishable-api-key: pk_..."
Publishable keys are scoped to a sales channel. They are safe to embed in client-side code (storefront JavaScript).
3. Customer: JWT or session cookie
Customer-authenticated store endpoints (e.g. /store/customers/me) require either:
- A customer Bearer JWT obtained from
POST /auth/customer/emailpass, or - The
connect.sidsession cookie (set automatically when customer logs in via the storefront).
curl -X POST https://shop.example.com/auth/customer/emailpass \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com","password":"hunter2"}'
4. Federation: no auth (public)
/store/marketplace/* endpoints on carphacom.com are public — no key required. Rate
limited per IP (60 requests/minute).
Errors
| Code | Meaning |
|---|---|
| 401 Unauthorized | Missing or invalid token / key. |
| 403 Forbidden | Token valid but lacks permission for this resource. |
| 400 not_allowed | Missing publishable key on a /store/* endpoint. |
| 429 Too Many Requests | Rate-limited. Back off per Retry-After header. |