API reference
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 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.
Attributes
idstring (uuid)OptionalnamestringOptionalhintstringOptionalThe key’s last 4 characters.
createdAtstring (date-time)OptionallastUsedAtstring (date-time)OptionalNullableexpiresAtstring (date-time)OptionalNullableWhen the key stops working; null never.
statusstringOptionalPossible values
activeexpiredrevokedrevokedAtstring (date-time)OptionalNullableWhen an owner revoked the key; null while it is not.
expectedintegerOptionalNullableHow many screens the owner expects to install with the key.
devicesintegerOptionalScreens that joined with the key.
unassignedintegerOptionalOf those, the ones not yet named or assigned.
refusedintegerOptionalHow many times the key was tried after it stopped working.
lastRefusedAtstring (date-time)OptionalNullablealertEmailbooleanOptionalexposedAtstring (date-time)OptionalNullableWhen a screen first proved a readable copy of the key on its PC; null never. The key keeps working until it is revoked.
lastCappedAtstring (date-time)OptionalNullableWhen screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.
Create an install key
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.
Body parameters
namestringRequiredWho or what the key is for.
expiresAtstring (date-time)OptionalWhen the key stops working (RFC 3339, in the future). Absent: it never expires.
expectedintegerOptionalHow many screens you expect to install with the key. Mestra tells you once if more join.
alertEmailbooleanOptionalMail the organisation’s owners (at most once an hour for the key) when the key is tried after it was revoked or expired.
Default
false
Returns
The key was made.
An object with:
idstring (uuid)OptionalnamestringOptionalhintstringOptionalThe key’s last 4 characters.
createdAtstring (date-time)OptionallastUsedAtstring (date-time)OptionalNullableexpiresAtstring (date-time)OptionalNullableWhen the key stops working; null never.
statusstringOptionalPossible values
activeexpiredrevokedrevokedAtstring (date-time)OptionalNullableWhen an owner revoked the key; null while it is not.
expectedintegerOptionalNullableHow many screens the owner expects to install with the key.
devicesintegerOptionalScreens that joined with the key.
unassignedintegerOptionalOf those, the ones not yet named or assigned.
refusedintegerOptionalHow many times the key was tried after it stopped working.
lastRefusedAtstring (date-time)OptionalNullablealertEmailbooleanOptionalexposedAtstring (date-time)OptionalNullableWhen a screen first proved a readable copy of the key on its PC; null never. The key keeps working until it is revoked.
lastCappedAtstring (date-time)OptionalNullableWhen screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.
keystringOptionalThe key itself, shown only in this answer.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | The name is missing or too long ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
List all install keys
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.
Query parameters
revokedbooleanOptionaltruelists the revoked keys too.
Returns
The keys.
Returns a list of Install key objects.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
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 |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Update an install key
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.
Path parameters
idstring (uuid)Required
Body parameters
namestringOptionalexpiresAtstring (date-time)OptionalNullableIn the future; null for no expiry.
expectedintegerOptionalNullablealertEmailbooleanOptional
Returns
The key as it is now.
Returns the Install key object.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | Nothing to change, or a value is not valid ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_install_keynot_connected |
|
409 | api_offinstall_key_revokedintegration_off |
|
413 | “body exceeds limit (<n> bytes)”. | |
501 | The player is not available on this server. |
Delete an install key
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.
Path parameters
idstring (uuid)Required
Query parameters
removeUnassignedbooleanOptionalSend
trueto remove the unnamed screens too,falseto keep them but still get the counts back. Absent:204, nothing else changes.
Returns
Revoked (removeUnassigned sent).
An object with:
keyobjectRequiredAn 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.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptionalhintstringOptionalThe key’s last 4 characters.
createdAtstring (date-time)OptionallastUsedAtstring (date-time)OptionalNullableexpiresAtstring (date-time)OptionalNullableWhen the key stops working; null never.
statusstringOptionalPossible values
activeexpiredrevokedrevokedAtstring (date-time)OptionalNullableWhen an owner revoked the key; null while it is not.
expectedintegerOptionalNullableHow many screens the owner expects to install with the key.
devicesintegerOptionalScreens that joined with the key.
unassignedintegerOptionalOf those, the ones not yet named or assigned.
refusedintegerOptionalHow many times the key was tried after it stopped working.
lastRefusedAtstring (date-time)OptionalNullablealertEmailbooleanOptionalexposedAtstring (date-time)OptionalNullableWhen a screen first proved a readable copy of the key on its PC; null never. The key keeps working until it is revoked.
lastCappedAtstring (date-time)OptionalNullableWhen screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.
removedintegerRequiredScreens this call removed.
keptintegerRequiredThe key’s screens that stay: named ones, ones tied to OpenCRS, and (with
false) the unnamed ones.
Errors
| Status | Code | Meaning |
|---|---|---|
400 |
| |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_install_keynot_connected |
|
409 | api_offintegration_offtry_again |
|
501 | The player is not available on this server. |