---
title: "Register a device (owner/admin; returns its key ONCE)"
method: POST
path: "/v1/projects/{project_id}/udp/devices"
tags: ["udp"]
---

# Register a device (owner/admin; returns its key ONCE)

`POST /v1/projects/{project_id}/udp/devices`

## Request

- Base URL: `https://api.wavehouse.cloud`
- URL: `https://api.wavehouse.cloud/v1/projects/{project_id}/udp/devices`
- Auth: one of:
  - API key in cookie `whc_session`
  - HTTP bearer
  - API key in header `X-API-Key`

Mints an 8-byte device id and, for every suite but `none`, a key. The key is returned ONCE, hex-encoded, and cannot be retrieved again — write it into the device now. `suite` and `nonce_len` are FIXED at registration and never change: a deployed device cannot be asked to re-read its own layout, so rotation is a new device and an overlap. An AEAD suite fixes `nonce_len` at the cipher's size; the others take 0, 4 or 8, and 4 or more is what lets NATS recognize a retry. A device with no durable counter and no clock must use `xchacha20-poly1305`, whose 24-byte nonce is safe to draw at random.

## Path parameters

- `project_id` string, required

## Headers

- `Idempotency-Key` string: A unique value you choose per logical request (a random UUID). A retry with the same key and the same request within 24 hours returns the first response, marked Idempotency-Replayed: true, instead of acting twice. The same key with a different request is refused with 422; one sent while the first is still running gets 409.

## Request body

- CreateUDPDeviceInput
  - `bytes_per_second` integer: bytes per second; 0 is unlimited
  - `content_encoding` '' | 'gzip' | 'zstd': how the device compresses the payload; the worker inflates it, the edge never does
  - `content_type` string, required: the media type the payload is posted to the engine under, e.g. application/x-ndjson
  - `expires_at` string, date-time: instant the device stops being accepted; omit for no expiry
  - `name` string: what to call this device in the console
  - `nonce_len` integer: nonce bytes. An AEAD suite fixes this; the others take 0, 4 or 8, and 4 or more is what lets a retry be recognized
  - `rate_per_second` number, double: datagrams per second; 0 is unlimited
  - `suite` string, required: the authentication/encryption suite; FIXED for the life of the device
  - `table` string, required: the table the payload is ingested into

## Response `201`

Created

- CreateUDPDeviceOutput
  - `bytes_per_second` integer, required: bytes per second the edge accepts; 0 is unlimited
  - `content_encoding` string: gzip or zstd when the device compresses; empty otherwise
  - `content_type` string, required: the media type the payload is posted to the engine under
  - `created_at` string, date-time, required
  - `created_by` string
  - `enabled` boolean, required
  - `expires_at` string, date-time: absent when the device does not expire
  - `id` string, required: 16 hex characters — the 8 bytes that lead every datagram
  - `key` string: the device's key, hex — shown ONCE and never retrievable again. Absent for the none suite, which has no key
  - `last_seen_at` string, date-time: batched: it trails live traffic by up to a minute
  - `name` string, required
  - `nonce_len` integer, required
  - `rate_per_second` number, double, required: datagrams per second the edge accepts; 0 is unlimited
  - `revoked_at` string, date-time: present once revoked
  - `status` string, required: active | disabled | revoked | expired
  - `suite` string, required
  - `table` string, required

## Other responses

- `429`: Rate limited, per client IP, API key or org; a client IP is also refused on every route for a while after repeated authentication failures. A limited operation carries RateLimit-Policy and RateLimit on every response; wait Retry-After seconds before retrying.
- `default`: Error

---

[API](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api.md) · [All operations](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/revisions/adea029bf505?raw)