---
title: "Enrol a tunnel host with its gateway"
method: POST
path: "/api/v0beta1/hosts/{id}/enrolment"
tags: ["Hosts"]
---

# Enrol a tunnel host with its gateway

`POST /api/v0beta1/hosts/{id}/enrolment`

## Request

- Base URL: `https://app.amika.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://app.amika.dev/api/v0beta1/hosts/{id}/enrolment`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `wos-session`

Returns everything `amika-hostd` needs to dial out: the credential, the generation the gateway fences on, and the gateway address with its path. Only for a host in `tunnel` mode; a `listen` host binds a port and is reached at its registered URL, so it is refused with 400. Only a signed-in user can enrol a host; an API key or other service identity is refused with 403. A POST rather than a GET so the credential is never cached or prefetched.

## Path parameters

- `id` string, required

## Response `200`

What the host needs to dial out.

- HostEnrolmentResponse
  - `credential` string, required: The host's secret, whole and opaque. Sent as `x-amika-host-credential` when the host dials the gateway.
  - `generation` integer, required: How many times this host's credential has been replaced. The gateway fences a stale connection with it, so a daemon that reconnects sends the generation it enrolled with.
  - `gateway_url` string, required: The WebSocket address to dial, path included.
  - `transport_mode` 'tunnel', required: Always `tunnel`. A `listen` host is refused: it binds a port and is reached at its registered URL.

## Other responses

- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Error

## Changes

- **2026-10-27** `58476e797178`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/amika/apis/amika-api/changes/api/v0beta1/hosts/:id/enrolment/post.md)

---

[API](https://skmtc.dev/amika/apis/amika-api.md) - [All operations](https://skmtc.dev/amika/apis/amika-api/llms.txt) - [OpenAPI document](https://skmtc.dev/amika/apis/amika-api/revisions/86f031a957c1?raw)