---
title: "Enroll a machine with a pre-authorized link key"
method: POST
path: "/api/link/preauth"
tags: ["link"]
---

# Enroll a machine with a pre-authorized link key

`POST /api/link/preauth`

## Request

- Base URL: `https://app.nerdit.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://app.nerdit.ai/api/link/preauth`
- Auth: none declared

Turn a key and a credential into the node identity the machine comes up as.

The response model is the claim route's own (D-X16-O7): a daemon that
can read one answer can read the other, and the shape being *the same
class* rather than a copy is what keeps it that way.

Everything that decides anything is in
:func:`~nerdit_cloud.nodes.preauth.consume_preauth_key`, including the
D-X16-O9 evaluation order this route must not second-guess. What is
here is the metering, the shape check that makes passing the plaintext
to ``forbidden_values`` safe, and the commit-then-raise the refusal path
shares with every other route in this codebase.

## Request body

- PreauthLinkRequest: What a machine sends to enroll itself (D-X16-O7 payload shape). Two load-bearing fields and one display string. The key authorises; the credential is what gets enrolled and is the value D-X16-O9's idempotency is keyed on. ``hostname_hint`` is the stem of the slug and the node's initial display name — this route is unauthenticated, so it is attacker-chosen text (D-X16-O23), bounded here and normalised before it is written.
  - `key` string, required
  - `credential_reference` string, required
  - `hostname_hint` string, nullable

## Response `200`

Successful Response

- LinkClaimResponse: Non-secret node identity; capability material is never issued here.
  - `node_id` string, uuid, required
  - `node_slug` string, required
  - `nodes_base_domain` string, required

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Too Many Requests

---

[API](https://skmtc.dev/nerdit/apis/nerdit-cloud-web.md) · [All operations](https://skmtc.dev/nerdit/apis/nerdit-cloud-web/llms.txt) · [OpenAPI document](https://skmtc.dev/nerdit/apis/nerdit-cloud-web/revisions/06e3b44b58be?raw)