# Companies and domains

Authorise a company by its domain, give out its addresses, and run its admins and holders.

A company proves it controls its domain once. It receives a company subdomain of seleya.email, such as `acme.seleya.email`. It can also set up its own mail subdomain, `agents.acme.com`, by publishing the mail records we provide. Mail from the company's proven domains counts as from colleagues.

The proven company domain (`acme.com`) identifies the company. It is distinct from the domains on which new agent addresses are issued (`acme.seleya.email` and, once verified, `agents.acme.com`). This does not move the company's existing email.

## Authorise a company

`POST /v1/companies` starts it, at address.seleya.ai or by an agent acting for the person who runs it:

```bash curl
curl -X POST https://address.seleya.ai/api/v1/companies \
  -H "Authorization: Bearer $SELEYA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Robotics Ltd", "domain": "acme.com", "country": "ZA", "method": "dns"}'
```

- `name` is the legal name and `country` where it is registered. Both are screened against sanctions lists.
- `domain` is the domain the company's people's email is on, not a subdomain.
- `method` is how it proves the domain: `dns`, one text record we give you; or `mail`, the mail records that let `agents.<domain>` send and receive here, which prove the domain too.

The answer lists the records. Publish them at the domain's DNS host, then call `POST /v1/companies/authorisations/{id}/check`. DNS changes can take a few minutes to be seen. Once proven, the company is set up (its subdomain, its sending and its records), which takes a few minutes more; the authorisation's status then reads `done`, with the company.

## Give out addresses

An admin gives out an address with `POST /v1/addresses`:

| Field | What it is |
| --- | --- |
| `local` | The name before the @ |
| `display_name` | The name people see; it must say it is an agent |
| `domain` | Optional: the company's seleya.email subdomain (the default), or its own verified mail subdomain |
| `holder_email` | The person accountable for it, who is told by email |
| `label` | Names the address's first key |

The answer carries the address's first key, shown once. For example, pass `"domain": "agents.acme.com"` to issue `desk@agents.acme.com` after that mail domain is verified. Someone whose email is at the company's proven domain can also claim an address on its seleya.email subdomain with `POST /v1/addresses/self`.

## Keys

An address key acts for one address. An owner key (`POST /v1/keys` with `owner`) acts for every address the company owns, for the company's own automation. To rotate a key, make a second, move the agent to it, then revoke the first.

## Admins and holders

- **Admins** run the company: its addresses, keys, billing and admins. A company keeps at least one.
- **A holder** is the person accountable for one address. Moving it to someone else keeps the address and its history.
- **Retiring** an address stops it receiving and sending and ends its keys. Its name is never given out again.

From a key or app, adding or removing an admin, changing a holder and retiring wait for the company's admins ([What only a person may do](https://address.seleya.ai/docs/only-a-person/)).