# Install keys

An install key is installed on new screens so that they join the organisation without showing a pairing code. One key installs any number of screens until it is revoked. The key's value is shown once, when it is made. See [Install and connect a screen](https://withmestra.com/docs/player/install/) for the guide.

An install key is installed on new screens so that they join the organisation without showing a pairing code. One key installs any number of screens until it is revoked. The key's value is shown once, when it is made. See [Install and connect a screen](https://withmestra.com/docs/player/install/) for the guide.

## The Install key object

An install key: its name and last four characters, when it was made, used and expires, how many screens it was expected to install and has installed, and whether it is active, expired or revoked.

- `id` (string (uuid), optional):
- `name` (string, optional):
- `hint` (string, optional): The key's last 4 characters.
- `createdAt` (string (date-time), optional):
- `lastUsedAt` (string (date-time), optional, nullable):
- `expiresAt` (string (date-time), optional, nullable): When the key stops working; null never.
- `status` (string, optional):  One of: `active`, `expired`, `revoked`.
- `revokedAt` (string (date-time), optional, nullable): When an owner revoked the key; null while it is not.
- `expected` (integer, optional, nullable): How many screens the owner expects to install with the key.
- `devices` (integer, optional): Screens that joined with the key.
- `unassigned` (integer, optional): Of those, the ones not yet named or assigned.
- `refused` (integer, optional): How many times the key was tried after it stopped working.
- `lastRefusedAt` (string (date-time), optional, nullable):
- `alertEmail` (boolean, optional):
- `exposedAt` (string (date-time), optional, nullable): When a screen first proved a readable copy of the key on its PC; null never. The key keeps working until it is revoked.
- `lastCappedAt` (string (date-time), optional, nullable): When screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.

```json
{
  "id": "string",
  "name": "string",
  "hint": "string",
  "createdAt": "string",
  "lastUsedAt": "string",
  "expiresAt": "string",
  "status": "active",
  "revokedAt": "string",
  "expected": 0,
  "devices": 0,
  "unassigned": 0,
  "refused": 0,
  "lastRefusedAt": "string",
  "alertEmail": false,
  "exposedAt": "string",
  "lastCappedAt": "string"
}
```

## Create an install key

`POST /api/v1/player/install-keys`

Permission: Screens · Write.

Needs the Screens write permission and an owner. Makes a key to install on new screens: a screen installed with it joins this organisation without showing a pairing code. The key (`key`) is shown once in this answer; store it as a secret, it cannot be read again. One key installs any number of screens until it is revoked. Mestra screens must be on and connected. A key limited to some screens gets 403 `screens_limited`: an install key enrols a screen into the whole organisation.

### Parameters

- `name` (string, required): Who or what the key is for.
- `expiresAt` (string (date-time), optional): When the key stops working (RFC 3339, in the future). Absent: it never expires.
- `expected` (integer, optional): How many screens you expect to install with the key. Mestra tells you once if more join.
- `alertEmail` (boolean, optional): Mail the organisation's owners (at most once an hour for the key) when the key is tried after it was revoked or expired.

### Returns

The key was made.

An object with:

- `id` (string (uuid), optional):
- `name` (string, optional):
- `hint` (string, optional): The key's last 4 characters.
- `createdAt` (string (date-time), optional):
- `lastUsedAt` (string (date-time), optional, nullable):
- `expiresAt` (string (date-time), optional, nullable): When the key stops working; null never.
- `status` (string, optional):  One of: `active`, `expired`, `revoked`.
- `revokedAt` (string (date-time), optional, nullable): When an owner revoked the key; null while it is not.
- `expected` (integer, optional, nullable): How many screens the owner expects to install with the key.
- `devices` (integer, optional): Screens that joined with the key.
- `unassigned` (integer, optional): Of those, the ones not yet named or assigned.
- `refused` (integer, optional): How many times the key was tried after it stopped working.
- `lastRefusedAt` (string (date-time), optional, nullable):
- `alertEmail` (boolean, optional):
- `exposedAt` (string (date-time), optional, nullable): When a screen first proved a readable copy of the key on its PC; null never. The key keeps working until it is revoked.
- `lastCappedAt` (string (date-time), optional, nullable): When screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.
- `key` (string, optional): The key itself, shown only in this answer.

### Errors

- 400: The name is missing or too long (`field` is `name`), `expiresAt` is not in the future (`field` is `expiresAt`), or `expected` is below 1 (`field` is `expected`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request POST \
  --url https://app.withmestra.com/api/v1/player/install-keys \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Install batch A","expected":4}'
```

## List all install keys

`GET /api/v1/player/install-keys`

Permission: Screens · Write.

Needs the Screens write permission and an owner. The keys' values are never shown; `hint` is the last 4 characters. Expired keys are listed with `status` `expired`. Revoked keys are left out unless `revoked=true`, which lists them too (with `status` `revoked`). A key limited to some screens gets 403 `screens_limited`: an install key enrols a screen into the whole organisation.

### Parameters

- `revoked` (boolean, optional): `true` lists the revoked keys too.

### Returns

The keys.

### Errors

- 400: `revoked` is not true or false.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off`.
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/install-keys \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Update an install key

`PATCH /api/v1/player/install-keys/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an owner. Send only what changes. `expiresAt` and `expected` take `null` to clear them. Raising `expected` (or clearing it) lets the "more screens than expected" alert fire again. A revoked key cannot be changed (`409`, `install_key_revoked`). A key limited to some screens gets 403 `screens_limited`: an install key enrols a screen into the whole organisation.

### Parameters

- `id` (string (uuid), required):
- `name` (string, optional):
- `expiresAt` (string (date-time), optional, nullable): In the future; null for no expiry.
- `expected` (integer, optional, nullable):
- `alertEmail` (boolean, optional):

### Returns

The key as it is now.

### Errors

- 400: Nothing to change, or a value is not valid (`field` is `expiresAt` or `expected`).
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`unknown_install_key`, `not_connected`): `unknown_install_key`, or `not_connected`.
- 409 (`api_off`, `install_key_revoked`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `install_key_revoked`, or `integration_off`.
- 413: “body exceeds limit (\<n> bytes)”.
- 501: The player is not available on this server.

### Example request

```sh
curl --request PATCH \
  --url https://app.withmestra.com/api/v1/player/install-keys/string \
  --header "Authorization: Bearer $MESTRA_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Install batch B"}'
```

## Delete an install key

`DELETE /api/v1/player/install-keys/{id}`

Permission: Screens · Write.

Needs the Screens write permission and an owner. Revokes the key: no new screen can join with it. Screens that already did stay, unless `removeUnassigned=true`: then the screens that joined with the key and have not been named or assigned are removed too (a screen tied to an OpenCRS screen is never removed; it counts in `kept`). The revoke is saved first; the removal then runs in steps of a few hundred screens, each saved as it goes. If the call fails or is cut off part way, the key is revoked and the screens removed so far stay removed: send it again (an already revoked key can be cleaned up this way) and it goes on from there. Without `removeUnassigned` the answer is `204` with no body. With it (`true` or `false`) the answer is `200` with the key, how many screens this call removed and how many of the key's screens stay. A key limited to some screens gets 403 `screens_limited`: an install key enrols a screen into the whole organisation.

### Parameters

- `id` (string (uuid), required):
- `removeUnassigned` (boolean, optional): Send `true` to remove the unnamed screens too, `false` to keep them but still get the counts back. Absent: `204`, nothing else changes.

### Returns

Revoked (`removeUnassigned` sent).

An object with:

- `key` (object, required): An install key: its name and last four characters, when it was made, used and expires, how many screens it was expected to install and has installed, and whether it is active, expired or revoked.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
  - `hint` (string, optional): The key's last 4 characters.
  - `createdAt` (string (date-time), optional):
  - `lastUsedAt` (string (date-time), optional, nullable):
  - `expiresAt` (string (date-time), optional, nullable): When the key stops working; null never.
  - `status` (string, optional):  One of: `active`, `expired`, `revoked`.
  - `revokedAt` (string (date-time), optional, nullable): When an owner revoked the key; null while it is not.
  - `expected` (integer, optional, nullable): How many screens the owner expects to install with the key.
  - `devices` (integer, optional): Screens that joined with the key.
  - `unassigned` (integer, optional): Of those, the ones not yet named or assigned.
  - `refused` (integer, optional): How many times the key was tried after it stopped working.
  - `lastRefusedAt` (string (date-time), optional, nullable):
  - `alertEmail` (boolean, optional):
  - `exposedAt` (string (date-time), optional, nullable): When a screen first proved a readable copy of the key on its PC; null never. The key keeps working until it is revoked.
  - `lastCappedAt` (string (date-time), optional, nullable): When screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.
- `removed` (integer, required): Screens this call removed.
- `kept` (integer, required): The key's screens that stay: named ones, ones tied to OpenCRS, and (with `false`) the unnamed ones.

### Errors

- 400: `removeUnassigned` is not true or false.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`unknown_install_key`, `not_connected`): `unknown_install_key`, or `not_connected`.
- 409 (`api_off`, `integration_off`, `try_again`): `api_off` (an owner hasn't turned the API on), or `integration_off`, or `try_again` (a change collided with this one; what was saved before it stays, and sending the call again does the rest).
- 501: The player is not available on this server.

### Example request

```sh
curl --request DELETE \
  --url https://app.withmestra.com/api/v1/player/install-keys/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
