Authentication

OmniCart uses four authentication patterns depending on the route category.

Admin Authentication#

Admin routes (/admin/*) require a valid admin JWT token obtained through the OmniCart authentication endpoints.

Required Header:

Authorization: Bearer <admin_jwt_token>

Example: Get Admin User

curl -X GET 'https://your-store.omnicart.cc/admin/brands' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

How to Obtain Admin Token:

# Login as admin user
curl -X POST 'https://your-store.omnicart.cc/auth/user/emailpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "admin@example.com",
    "password": "your_password"
  }'

# Response contains token
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Authentication Enforcement:

Admin authentication is enforced at the framework level
All /admin/* routes automatically require authentication
Invalid or missing tokens return 401 Unauthorized
JWT tokens expire after 7 days by default (deployment-configurable) — always re-authenticate on a 401 rather than assuming a fixed lifetime
A session token can be refreshed via POST /auth/token/refresh (send the current bearer token)

Secret API Keys (recommended for server-to-server)#

For scheduled jobs, BI pipelines, and backend integrations, prefer a secret API key over email/password JWT logins: keys don't expire on a timer, aren't tied to a person's password, and can be revoked individually. Create one in the admin dashboard under Settings → API Key Management (secret keys start with sk_).

Use it with HTTP Basic auth — the key is the username, the password is empty:

curl -X GET 'https://your-store.omnicart.cc/admin/orders?limit=10' \
  -u "sk_YOUR_SECRET_KEY:"

# equivalent explicit header form
curl -X GET 'https://your-store.omnicart.cc/admin/orders?limit=10' \
  -H 'Authorization: Basic sk_YOUR_SECRET_KEY'

Most admin endpoints accept secret keys; a small number of sensitive operations require an interactive user session or JWT instead — if a key gets a 401 on a specific route, fall back to the JWT flow for that call.

Partner Authentication#

Partner routes (/store/partners/*) use bearer token or session-based authentication with varying requirements.

Required Header:

Authorization: Bearer <partner_jwt_token>

Example: Get Partner Profile

curl -X GET 'https://your-store.omnicart.cc/store/partners/me' \
  -H 'x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'

Authentication Patterns:

Required Authentication:
- Routes: /store/partners/me, /store/partners/me/*
- Must have valid partner token
- Returns 401 if not authenticated
Registration (Allow Unregistered):
- Route: /store/partners/auth/register (POST)
- Requires auth identity but allows unregistered partners
- Used for completing registration after email verification
Optional Authentication:
- Route: /store/partners/offers (GET)
- Works without authentication (public list)
- Personalized if authenticated
- Uses allowUnauthenticated: true

How to Obtain Partner Token:

# Register partner (Step 1: Create auth identity)
curl -X POST 'https://your-store.omnicart.cc/auth/partner/emailpass/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "partner@example.com",
    "password": "secure_password"
  }'

# Step 2: Complete partner registration
curl -X POST 'https://your-store.omnicart.cc/store/partners/auth/register' \
  -H 'x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY' \
  -H 'Authorization: Bearer <temp_token_from_step1>' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Example Corp",
    "contact_name": "John Doe",
    "phone": "+1-555-0100"
  }'

# Login (subsequent requests)
curl -X POST 'https://your-store.omnicart.cc/auth/partner/emailpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "partner@example.com",
    "password": "secure_password"
  }'

Customer Authentication#

Store routes (/store/*) support optional customer authentication for personalization.

Required Header — Publishable API Key:

Every /store/* request must include your publishable API key (starts with pk_). It identifies your storefront and scopes results to the correct sales channel. Requests without it are rejected. Get yours from the admin dashboard under Settings → API Key Management (or from your onboarding materials).

x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY

Optional Header — Customer Token:

Authorization: Bearer <customer_jwt_token>

Example: List Products (Public)

# Without authentication (public catalog)
curl -X GET 'https://your-store.omnicart.cc/store/products' \
  -H 'x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY'

# With authentication (personalized pricing, recommendations)
curl -X GET 'https://your-store.omnicart.cc/store/products' \
  -H 'x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY' \
  -H 'Authorization: Bearer <customer_token>'

Example: Get Cart (Requires Auth)

curl -X GET 'https://your-store.omnicart.cc/store/carts/my-cart' \
  -H 'x-publishable-api-key: pk_YOUR_PUBLISHABLE_KEY' \
  -H 'Authorization: Bearer <customer_token>'

How to Obtain Customer Token:

# Register customer
curl -X POST 'https://your-store.omnicart.cc/auth/customer/emailpass/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "password": "secure_password"
  }'

# Login
curl -X POST 'https://your-store.omnicart.cc/auth/customer/emailpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "password": "secure_password"
  }'

Public Endpoints#

Public routes require no authentication and are typically used for:

Webhooks from external services
Embedded widgets (Flow Builder)
Tracking pixels
Demo pages

Example: Flow Builder Embed

curl -X GET 'https://your-store.omnicart.cc/flow-builder/session/create?cart_id=cart_123'

Example: Webhook Receiver

curl -X POST 'https://your-store.omnicart.cc/webhooks/stripe' \
  -H 'Content-Type: application/json' \
  -H 'Stripe-Signature: t=1234,v1=abc...' \
  -d '{
    "type": "payment_intent.succeeded",
    "data": {...}
  }'

Note: Public endpoints may have other security measures:

Webhook signature verification
CORS restrictions (or origin: true for embeds)
Rate limiting
IP whitelisting