# Device connectors

This reference describes implemented code, not verified deployment or entitlement for every organisation. Confirm access with your own organisation before enabling an integration. Do not send production mutations while testing. REST base: `https://vilasdqkwlszlulteqrb.supabase.co/functions/v1/api-v1`.

REST uses organisation API keys or PATs in `Authorization: Bearer <token>`. Unbound PATs need `X-Org-Id` or `org_id`; bound credentials cannot select a different organisation. `write` includes `read`; `/v1/audit` needs `audit:read`. Role, department, ownership, record visibility and enabled modules still apply. Generic DELETE requires an administrator role.

## Boundary

The API accepts reports from an external agent in the laboratory network. It does not ship, install or certify an OPC UA/LADS agent. Certificate pinning, operating-system secret storage, buffering and instrument write-back depend on that agent and must be validated separately.

## Routes

`GET POST /v1/connectors`; `GET DELETE /v1/connectors/{id}`. GET needs read; POST needs write; DELETE requires administrator role. Connector POST does not implement Idempotency-Key or test mode.

```json
{"name":"lab-connector-01","status":"online","queue_depth":0,"devices":[{"external_device_id":"HPLC-07","vendor":"agilent","model":"1260 Infinity II","device_type":"hplc","opcua_endpoint_url":"opc.tcp://hplc-07.lab.example.com:4840","security_mode":"SignAndEncrypt","connection_status":"connected"}]}
```

POST upserts the connector by name and reported devices by external_device_id within the organisation. Device ownership is tied to the connector/key binding. Maximum devices reported per heartbeat: 200. The result-ingest auto-registration path caps devices at 500 per organisation; do not treat this as a universal connector cap. POST returns 200 with connector_id, devices, status and optional skipped_devices. Unencrypted OPC UA (`None`) is rejected; the reported values SignAndEncrypt and Sign are accepted. Sign alone does not imply encryption. This does not establish a mutual-certificate session on behalf of the external agent.

## Measurements

Send results to `POST /v1/results` (requires analytics_qc). Optional `sample_code`, `connector_id`, `lads` preserve routing context. Routing priority: explicit experiment/sample IDs; sample code; active equipment usage session; otherwise the unassigned inbox. The server records assignment_source and manual assignments are audited. Do not promise universal deduplication or automatic correct matching; review routing and unresolved results.