# `POST /api/v1/daemonx/onboarding/sessions`

> **Endpoint:** `POST /api/v1/daemonx/onboarding/sessions`  
> **Auth Scope:** Developer Token Protected (`Authorization: Bearer nyx_daemonx_live_...`)  
> **Target Service:** Nyxzie Cloud Core API  
> **Introduced In:** v1.0.0  
> **Last Updated:** v1.0.0  

---

## 1. Description & Purpose

`POST /api/v1/daemonx/onboarding/sessions` initiates a secure counter onboarding session for retail workstations. It generates an ephemeral 6-digit pairing code (valid for 900 seconds / 15 minutes) that a cashier or technician enters into the **DaemonX Windows Desktop App** to pair the workstation with Nyxzie Core.

Key characteristics:
1. **Server-to-Server B2B Security:** Called by your backend with a Developer API token (`nyx_daemonx_live_*` or `nyx_daemonx_sandbox_*`). The token is **never** shared with the cashier browser or desktop machine.
2. **Deterministic Entity Correlation:** Binds the session to your platform's customer/merchant reference (`external_customer_ref`), store branch (`external_location_ref`), and register lane (`external_counter_ref`).

---

## 2. Request Headers

| Header Name | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `Authorization` | `string` | **Yes** | Developer API Bearer Token | `Bearer nyx_daemonx_live_6b431eda073e...` |
| `Content-Type` | `string` | **Yes** | Payload format | `application/json` |
| `Accept` | `string` | No | Response format | `application/json` |

---

## 3. Request Payload

```typescript
export interface CreateOnboardingSessionRequest {
  external_customer_ref: string;
  external_location_ref?: string;
  external_counter_ref?: string;
  counter_name: string;
}
```

| Field | Type | Required | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- |
| `external_customer_ref` | `string` | **Yes** | 1–255 chars | Merchant / site identifier in your system. |
| `external_location_ref` | `string` | Optional | 1–255 chars | Store branch or venue identifier. |
| `external_counter_ref` | `string` | Optional | 1–255 chars | POS register lane or counter identifier. |
| `counter_name` | `string` | **Yes** | 2–100 chars | Friendly display name for the register. |

---

## 4. Successful Response (201 Created)

```json
{
  "success": true,
  "onboarding_session_id": "4b68ff5e-f001-4475-8025-a741544256eb",
  "pairing_code": "842915",
  "expires_in": 900,
  "onboarding_session": {
    "id": "4b68ff5e-f001-4475-8025-a741544256eb",
    "status": "pending",
    "external_customer_ref": "cust_milan_01",
    "external_location_ref": "loc_colombo_flagship",
    "external_counter_ref": "pos_lane_01",
    "counter_name": "Cashier Counter 1",
    "environment": "live",
    "is_sandbox": false,
    "counter_id": null,
    "completed_at": null,
    "expires_at": "2026-10-07T02:38:24.000Z",
    "created_at": "2026-10-07T02:33:24.000Z"
  }
}
```

---

## 5. TypeScript Contracts

```typescript
export interface DaemonxOnboardingSessionDTO {
  id: string;
  status: 'pending' | 'completed' | 'expired' | 'cancelled' | 'failed';
  external_customer_ref: string | null;
  external_location_ref?: string | null;
  external_counter_ref?: string | null;
  counter_name: string | null;
  environment: 'live' | 'sandbox';
  is_sandbox: boolean;
  counter_id?: string | null;
  completed_at?: string | null;
  expires_at: string;
  created_at: string;
}

export interface CreateOnboardingSessionResponse {
  success: true;
  onboarding_session_id: string;
  pairing_code: string;
  expires_in: number;
  onboarding_session: DaemonxOnboardingSessionDTO;
}

export interface DaemonxErrorResponse {
  success: false;
  error: string;
  code?: string;
}
```

---

## 6. Integration Snippets

### cURL
```bash
curl -X POST "https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions" \
  -H "Authorization: Bearer nyx_daemonx_live_6b431eda073e6cb462bd0a9971687376ef5481887c46dfa688bcb618982fc905" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_ref": "cust_milan_01",
    "external_location_ref": "loc_colombo_flagship",
    "external_counter_ref": "pos_lane_01",
    "counter_name": "Cashier Counter 1"
  }'
```

### TypeScript Backend Example
```typescript
import type { CreateOnboardingSessionResponse } from './types';

export async function createDaemonxPairingSession(
  apiToken: string,
  input: {
    customerRef: string;
    locationRef?: string;
    counterRef?: string;
    counterName: string;
  }
): Promise<CreateOnboardingSessionResponse> {
  const res = await fetch('https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken.trim()}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json',
    },
    body: JSON.stringify({
      external_customer_ref: input.customerRef.trim(),
      external_location_ref: input.locationRef?.trim(),
      external_counter_ref: input.counterRef?.trim(),
      counter_name: input.counterName.trim(),
    }),
  });

  if (!res.ok) {
    const errorBody = await res.json().catch(() => null);
    throw new Error(errorBody?.error || `Failed to create onboarding session (HTTP ${res.status})`);
  }

  return (await res.json()) as CreateOnboardingSessionResponse;
}
```