# `POST /api/v1/daemonx/onboarding/sessions/:id/cancel`

> **Endpoint:** `POST /api/v1/daemonx/onboarding/sessions/:id/cancel`  
> **Auth Scope:** Developer Token Protected (Writable Token Required)  
> **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/:id/cancel` cancels an active or pending onboarding pairing session before it is claimed or completed on a physical workstation.

Use cases:
1. **User Aborted Setup:** Cashier or administrator closes the pairing modal or clicks "Cancel" on the POS UI.
2. **Session Cleanup:** Invalidate an outstanding 6-digit pairing code before its 900-second TTL expires.
3. **Idempotent Invalidation:** Safe to call multiple times; already-cancelled sessions return the current cancelled session representation.

> [!NOTE]
> Sessions that have already transitioned to `"completed"` cannot be cancelled and will return a `409 Conflict` (`DAEMONX_ONBOARDING_COMPLETED`). To deactivate an already paired counter, use the counter unpair lifecycle.

---

## 2. Request Headers

| Header Name | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `Authorization` | `string` | **Yes** | Developer API Bearer Token (must have write permissions) | `Bearer nyx_daemonx_live_6b431eda073e...` |
| `Content-Type` | `string` | No | Body media type | `application/json` |
| `Accept` | `string` | No | Response format | `application/json` |

---

## 3. Path Parameters

| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `id` | `string` (UUID) | **Yes** | The onboarding session UUID to cancel. | `4b68ff5e-f001-4475-8025-a741544256eb` |

---

## 4. Request Body

This endpoint is an empty-body command action. No parameters are required.

```json
{}
```

---

## 5. Successful Response Example (200 OK)

```json
{
  "success": true,
  "onboarding_session": {
    "id": "4b68ff5e-f001-4475-8025-a741544256eb",
    "status": "cancelled",
    "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"
  }
}
```

---

## 6. Error Responses

### 6.1. Cannot Cancel Completed Session (`409 Conflict`)
If the workstation has already completed pairing and bound to the session:
```json
{
  "success": false,
  "error": "Completed DaemonX onboarding sessions cannot be cancelled.",
  "code": "DAEMONX_ONBOARDING_COMPLETED"
}
```

### 6.2. Session Not Found (`404 Not Found`)
If the session UUID does not exist or belongs to another developer profile:
```json
{
  "success": false,
  "error": "DaemonX onboarding session not found.",
  "code": "DAEMONX_ONBOARDING_SESSION_NOT_FOUND"
}
```

### 6.3. Read-Only Token Used (`403 Forbidden`)
If a read-only developer token attempts to cancel a session:
```json
{
  "success": false,
  "error": "DaemonX token does not have write permissions.",
  "code": "DAEMONX_TOKEN_READ_ONLY"
}
```

---

## 7. TypeScript Contracts

```typescript
export interface DaemonxOnboardingSessionCancelResponse {
  success: true;
  onboarding_session: {
    id: string;
    status: 'cancelled';
    external_customer_ref: string | null;
    external_location_ref?: string | null;
    external_counter_ref?: string | null;
    counter_name: string;
    environment: 'live' | 'sandbox';
    is_sandbox: boolean;
    counter_id?: string | null;
    completed_at?: string | null;
    expires_at: string;
    created_at: string;
  };
}
```

---

## 8. cURL Example

```bash
curl -X POST https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions/4b68ff5e-f001-4475-8025-a741544256eb/cancel \
  -H "Authorization: Bearer nyx_daemonx_live_6b431eda073e6cb462bd0a9971687376ef5481887c46dfa688bcb618982fc905" \
  -H "Content-Type: application/json" \
  -d '{}'
```