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.sid session 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. |