---
title: "Add or replace an authorized client"
method: POST
path: "/platform/deployments/{id}/onion/clients"
tags: ["Platform"]
---

# Add or replace an authorized client

`POST /platform/deployments/{id}/onion/clients`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/platform/deployments/{id}/onion/clients`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Tor v3 restricted discovery: submit a locally generated X25519
public key (base32, 52 chars), or `generate: true` to have one
minted — the private key is returned ONCE and never stored.
Every client-list change restarts the host's shared Tor daemon
briefly (invalidating existing rendezvous state is the point);
onion connections for other apps on the same server may blip
while containers keep running. Revoking the last client makes
the service public again. Requires the `manage` scope and an
agent announcing `onion-auth-v1`.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string, required
  - `pubkey` string: Base32 X25519 public key (52 chars). Mutually exclusive with generate.
  - `generate` boolean: Mint a keypair server-side; the private key is displayed exactly once.

## Response `200`

Client authorized; an onion_auth_update command carries the full active list.

## Other responses

- `400`: Invalid name or key, or both pubkey and generate.
- `401`: Invalid or missing API credentials
- `404`: Resource not found
- `422`: Agent does not announce onion-auth-v1.

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)