---
title: "Create an organization beacon"
method: POST
path: "/v1/organizations/{organization_id}/beacons/"
tags: ["organizations"]
---

# Create an organization beacon

`POST /v1/organizations/{organization_id}/beacons/`

## Request

- Base URL: `https://api.ethiack.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ethiack.com/v1/organizations/{organization_id}/beacons/`
- Auth: none declared

Provision a beacon for an organization.

Scoped to organization and partner integrators. Reserves a rathole
port and generates a WireGuard configuration; the response carries
the server configuration, which is returned exactly once here and
never persisted or retrievable again.

Args:
    organization_id (int): Identifier of the organization.
    body (CreateBeaconRequest): Beacon name, CIDRs, and optional
        DNS/interface settings.
    db (AsyncSession): Request-scoped database session.
    context (ActiveContext): Resolved caller identity and scope.

Returns:
    BeaconCreatedResponse: The provisioned beacon and its one-time
        WireGuard server config.

## Path parameters

- `organization_id` integer, required

## Request body

- CreateBeaconRequest: Request body for provisioning a new organization beacon. Field-level validation (name charset, private-CIDR, DNS IP format) is not duplicated here — ``BeaconProvisioningWorkflow`` already validates all of these and raises a clear ``ValueError`` (mapped to 400) on failure; re-validating in the schema would just be a second copy of the same rules to keep in sync. Attributes: name (str): Unique beacon name within the organization. allowed_cidrs (list[str]): Private CIDRs reachable through the tunnel. dns_server (str | None): Optional DNS server pushed to clients. interface_name (str | None): Optional host interface for NAT masquerade.
  - `name` string, required
  - `allowed_cidrs` string[], required
  - `dns_server` string, nullable
  - `interface_name` string, nullable

## Response `201`

Successful Response

- BeaconCreatedResponse: Response from a successful beacon creation. Attributes: wireguard_config (str | None): The WireGuard server config — returned exactly once, at creation time; never stored or retrievable again afterward.
  - `id` integer, required
  - `name` string, required
  - `status` integer, required
  - `last_seen` string, date-time, nullable, required
  - `created` string, date-time, required
  - `allowed_cidrs` string[], nullable
  - `dns_server` string, nullable
  - `interface_name` string, nullable
  - `version` integer, required
  - `beacon_token` string, nullable
  - `rathole_server` string, nullable
  - `rathole_public_port` integer, nullable
  - `wireguard_config` string, nullable
  - `rathole_control_port` integer, required: Rathole control port (always the default)

## Other responses

- `422`: Validation Error

---

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