:id`

Endpoint: GET /api/v1/daemonx/onboarding/sessions/:id
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

GET /api/v1/daemonx/onboarding/sessions/:id resolves the canonical lifecycle status of an existing onboarding session.

Use cases:

Pairing Status Polling / Verification: Check if the cashier has entered the 6-digit code in their desktop app and if workstation pairing has completed.
Post-Pairing Metadata Resolution: Once the session transitions to "completed", this endpoint reveals the newly issued counter_id assigned to the physical workstation.
Timeout / Expiration Inspection: Detect if a pairing session expired ("expired") or failed ("failed").

2. Request Headers

Header Name	Type	Required	Description	Example
`Authorization`	`string`	Yes	Developer API Bearer Token	`Bearer nyx_daemonx_live_6b431eda073e...`
`Accept`	`string`	No	Response format	`application/json`

3. Path Parameters

Parameter	Type	Required	Description	Example
`id`	`string` (UUID)	Yes	Onboarding session UUID returned when creating the session.	`4b68ff5e-f001-4475-8025-a741544256eb`

4. Successful Response Examples (200 OK)

State A: Session Completed (Workstation Paired)

{
  "success": true,
  "onboarding_session": {
    "id": "4b68ff5e-f001-4475-8025-a741544256eb",
    "status": "completed",
    "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": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
    "completed_at": "2026-10-07T02:35:10.000Z",
    "expires_at": "2026-10-07T02:38:24.000Z",
    "created_at": "2026-10-07T02:33:24.000Z"
  }
}

State B: Session Pending (Waiting for Code Entry on Desktop)

{
  "success": true,
  "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. Lifecycle Status Values

Status	Meaning	Next Action
`pending`	Pairing code has been issued and is awaiting desktop activation.	Continue polling or listen to SSE/webhook events.
`completed`	The workstation was successfully registered and activated.	Safe to dispatch print jobs using the returned `counter_id`.
`expired`	The 900-second TTL elapsed without being entered.	Generate a fresh pairing session.
`cancelled`	The session was cancelled via the developer API before pairing.	Ignore this session.
`failed`	Machine binding failed during pairing (e.g. invalid machine profile).	Review error logs or request a new code.

6. 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 GetOnboardingSessionResponse {
  success: true;
  onboarding_session: DaemonxOnboardingSessionDTO;
}

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

7. Integration Snippets

cURL

curl -X GET "https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions/4b68ff5e-f001-4475-8025-a741544256eb" \
  -H "Authorization: Bearer nyx_daemonx_live_6b431eda073e6cb462bd0a9971687376ef5481887c46dfa688bcb618982fc905" \
  -H "Accept: application/json"

TypeScript Client Function

import type { GetOnboardingSessionResponse, DaemonxOnboardingSessionDTO } from './types';

export async function getDaemonxOnboardingSession(
  apiToken: string,
  sessionId: string
): Promise<DaemonxOnboardingSessionDTO> {
  const res = await fetch(`https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions/${encodeURIComponent(sessionId)}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken.trim()}`,
      'Accept': 'application/json',
    },
  });

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

  const data = (await res.json()) as GetOnboardingSessionResponse;
  return data.onboarding_session;
}

Check Pairing Session