# A site posts its public key with its enrollment code

POST

/v1/auth/sites/enroll

```sh
curl --request POST \
  --url https://example.com/v1/auth/sites/enroll \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example", "publicKey": {} }'
```

Public: the code is the credential. The site keeps its private key; Kindgi stores the public one, and answers the site’s id (its statements’ `iss`) and the audience (their `aud`). A wrong, used or expired code, or one for a paused or unregistered site, gets one answer: `401 site-enrollment-refused`. Failures are limited per client (`429 rate-limit-exceeded`, with `Retry-After`). The body is at most 4096 bytes.

## Request Bodyrequired

application/json

object

**code**

required

string

\>= 1 characters <= 200 characters

**publicKey**

required

The site’s Ed25519 public key, a JWK: `kty: OKP`, `crv: Ed25519`, `x` and `kid`.

object

**_key_**

additional properties

any

##### Examplegenerated

```json
{
  "code": "example",
  "publicKey": {}
}
```

## Responses

### 200

The site’s id and its statements’ audience.

application/json

object

**siteId**

required

What the site’s statements carry as `iss`.

string format: uuid

**audience**

required

What the site’s statements carry as `aud`.

string

##### Examplegenerated

```json
{
  "siteId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "audience": "example"
}
```

### 400

A malformed body, or a public key that isn’t an Ed25519 JWK with a `kid`, or has a private part (`site-key-invalid`); it’s checked before the code.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 401

The code was refused (`site-enrollment-refused`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 413

The body is over 4096 bytes (`site-request-too-large`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 429

Too many failures from this client.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [Error code `site-enrollment-refused`](https://docs.kindgi.com/reference/errors.md#site-enrollment-refused)
- [Error code `site-key-invalid`](https://docs.kindgi.com/reference/errors.md#site-key-invalid)
- [Error code `site-request-too-large`](https://docs.kindgi.com/reference/errors.md#site-request-too-large)
- [Every error code](https://docs.kindgi.com/reference/errors.md)