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:

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

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)

{
  "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

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

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

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;
}

Create Pairing Session