# Agencies and clients

> Create a client for each end customer, assign their domains, add domains in bulk and give the client's people access to their domains only.

An agency manages many end customers from one organization. **Clients** are sub-accounts inside the organization:
each domain can belong to one client, and members and API tokens limited to a client only see and manage that client's
domains. Every client's domains use the same [nameserver pair](https://developers.openwaf.dev/dns/delegate-a-zone/), so all your customers get the
same instructions.

## Create a client

You need the `tech` role or higher, for the whole organization.

**Dashboard**

Open **Clients › New client**. Enter the name and, optionally, a **Contact email** and an internal **Note** (only your
organization sees it).
**CLI**

```sh
openwaf-cloud ctl clients add "Acme Shoes" contact_email=it@example.com --reason "New client"
```
**API**

```sh
curl -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/clients" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Shoes", "contact_email": "it@example.com"}'
```


Client names are unique in the organization (up to 200 characters, without commas or line breaks); notes are up to
2,000 characters. Admins can edit and delete clients.

## Assign a domain to a client

Choose the client when you add the domain, or change it later. The assignment is a [versioned change](https://developers.openwaf.dev/dns/zone-versions/)
of the zone. You need the `tech` role or higher, for the whole organization.

**Dashboard**

Open the domain's **Overview**, find **Client**, choose the client and select **Change client**.
**CLI**

```sh
openwaf-cloud ctl zones set-client example.com "Acme Shoes" --reason "Belongs to Acme Shoes"
openwaf-cloud ctl zones set-client example.com - --reason "No client"
```
**API**

```sh
curl -X PATCH "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Change-Reason: Belongs to Acme Shoes" \
  -d '{"client_id": "'"$CLIENT"'"}'
```
Send `{"client_id": null}` to remove the client.
**MCP**

`add_zone` accepts a `client_id` (see `list_clients`) when the domain is added.


## Add many domains at once

**Bulk add** creates one delegated domain per line from a pasted list or an uploaded CSV file:

```text
domain,client
example.com,Acme Shoes
example.org,Acme Shoes
example.net
```

- Each line is `domain[,client]`; the header line `domain,client` is optional and `#` starts a comment.
- A client named on a line is created if it does not exist yet.
- Lines are independent: a failing line (for example `zone_exists`) does not stop the others, and the result lists the
  outcome of each line.
- Up to 1,000 domains per upload. For uploads of up to 50 domains, the public records of each domain are imported too;
  for bigger uploads, scan them later from each domain's records.

The API equivalent is `POST /v1/orgs/{org}/zones/bulk` with the CSV as the request body.

## Give a client's people access

Invite a member limited to the client, or create an API token limited to it. Client-scoped members and tokens can only
have the `tech` or `readonly` role. They:

- see only the domains of their client, and the domains they add are assigned to it;
- cannot see the organization's member list, clients other than theirs, or tokens of others;
- with `tech`, can read the audit log entries of their client's domains.

See [Team members](https://developers.openwaf.dev/fundamentals/team-members/) and [API tokens](https://developers.openwaf.dev/fundamentals/api-tokens/#scopes).

## Delete a client

Admins can delete a client that has no domains. Move its domains to another client (or to none) first; otherwise the
deletion is refused with `409 client_has_zones`. Members, invitations and API tokens limited to the client are deleted
with it.

## Brand your service

Show your agency's brand instead of OpenWAF, open the dashboard on your own domain and give your customers nameservers
under your own name: see [White-label dashboard](https://developers.openwaf.dev/fundamentals/white-label/).