# 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**
```bash
curl -X GET 'https://your-store.omnicart.cc/admin/brands' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json'
```

**How to Obtain Admin Token:**
```bash
# 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:

```bash
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**
```bash
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:**

1. **Required Authentication:**
   - Routes: `/store/partners/me`, `/store/partners/me/*`
   - Must have valid partner token
   - Returns 401 if not authenticated

2. **Registration (Allow Unregistered):**
   - Route: `/store/partners/auth/register` (POST)
   - Requires auth identity but allows unregistered partners
   - Used for completing registration after email verification

3. **Optional Authentication:**
   - Route: `/store/partners/offers` (GET)
   - Works without authentication (public list)
   - Personalized if authenticated
   - Uses `allowUnauthenticated: true`

**How to Obtain Partner Token:**
```bash
# 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)**
```bash
# 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)**
```bash
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:**
```bash
# 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**
```bash
curl -X GET 'https://your-store.omnicart.cc/flow-builder/session/create?cart_id=cart_123'
```

**Example: Webhook Receiver**
```bash
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

---