Skip to content

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)Optional
  • namestringOptional
  • hintstringOptional

    The key’s last 4 characters.

  • createdAtstring (date-time)Optional
  • lastUsedAtstring (date-time)OptionalNullable
  • expiresAtstring (date-time)OptionalNullable

    When the key stops working; null never.

  • statusstringOptional

    Possible valuesactiveexpiredrevoked

  • revokedAtstring (date-time)OptionalNullable

    When an owner revoked the key; null while it is not.

  • expectedintegerOptionalNullable

    How many screens the owner expects to install with the key.

  • devicesintegerOptional

    Screens that joined with the key.

  • unassignedintegerOptional

    Of those, the ones not yet named or assigned.

  • refusedintegerOptional

    How many times the key was tried after it stopped working.

  • lastRefusedAtstring (date-time)OptionalNullable
  • alertEmailbooleanOptional
  • exposedAtstring (date-time)OptionalNullable

    When 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)OptionalNullable

    When screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.

Create an install key

PermissionScreens · 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.

Body parameters

  • namestringRequired

    Who or what the key is for.

  • expiresAtstring (date-time)Optional

    When the key stops working (RFC 3339, in the future). Absent: it never expires.

  • expectedintegerOptional

    How many screens you expect to install with the key. Mestra tells you once if more join.

  • alertEmailbooleanOptional

    Mail the organisation’s owners (at most once an hour for the key) when the key is tried after it was revoked or expired.

    Defaultfalse

Returns

The key was made.

An object with:

  • idstring (uuid)Optional
  • namestringOptional
  • hintstringOptional

    The key’s last 4 characters.

  • createdAtstring (date-time)Optional
  • lastUsedAtstring (date-time)OptionalNullable
  • expiresAtstring (date-time)OptionalNullable

    When the key stops working; null never.

  • statusstringOptional

    Possible valuesactiveexpiredrevoked

  • revokedAtstring (date-time)OptionalNullable

    When an owner revoked the key; null while it is not.

  • expectedintegerOptionalNullable

    How many screens the owner expects to install with the key.

  • devicesintegerOptional

    Screens that joined with the key.

  • unassignedintegerOptional

    Of those, the ones not yet named or assigned.

  • refusedintegerOptional

    How many times the key was tried after it stopped working.

  • lastRefusedAtstring (date-time)OptionalNullable
  • alertEmailbooleanOptional
  • exposedAtstring (date-time)OptionalNullable

    When 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)OptionalNullable

    When screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.

  • keystringOptional

    The key itself, shown only in this answer.

Errors

StatusCodeMeaning
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).

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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.

404not_connected

not_connected.

409api_offintegration_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.

List all install keys

PermissionScreens · 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.

Query parameters

  • revokedbooleanOptional

    true lists the revoked keys too.

Returns

The keys.

Returns a list of Install key objects.

Errors

StatusCodeMeaning
400

revoked is not true or false.

401invalid_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).

404not_connected

not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off.

501

The player is not available on this server.

Update an install key

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Body parameters

  • namestringOptional
  • expiresAtstring (date-time)OptionalNullable

    In the future; null for no expiry.

  • expectedintegerOptionalNullable
  • alertEmailbooleanOptional

Returns

The key as it is now.

Returns the Install key object.

Errors

StatusCodeMeaning
400

Nothing to change, or a value is not valid (field is expiresAt or expected).

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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.

404unknown_install_keynot_connected

unknown_install_key, or not_connected.

409api_offinstall_key_revokedintegration_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.

Delete an install key

PermissionScreens · 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.

Path parameters

  • idstring (uuid)Required

Query parameters

  • removeUnassignedbooleanOptional

    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:

  • keyobjectRequired

    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.

    Show child attributesHide child attributes
    • idstring (uuid)Optional
    • namestringOptional
    • hintstringOptional

      The key’s last 4 characters.

    • createdAtstring (date-time)Optional
    • lastUsedAtstring (date-time)OptionalNullable
    • expiresAtstring (date-time)OptionalNullable

      When the key stops working; null never.

    • statusstringOptional

      Possible valuesactiveexpiredrevoked

    • revokedAtstring (date-time)OptionalNullable

      When an owner revoked the key; null while it is not.

    • expectedintegerOptionalNullable

      How many screens the owner expects to install with the key.

    • devicesintegerOptional

      Screens that joined with the key.

    • unassignedintegerOptional

      Of those, the ones not yet named or assigned.

    • refusedintegerOptional

      How many times the key was tried after it stopped working.

    • lastRefusedAtstring (date-time)OptionalNullable
    • alertEmailbooleanOptional
    • exposedAtstring (date-time)OptionalNullable

      When 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)OptionalNullable

      When screens last tried to join with the key faster than Mestra allows (a leaked key looks like this); null never.

  • removedintegerRequired

    Screens this call removed.

  • keptintegerRequired

    The key’s screens that stay: named ones, ones tied to OpenCRS, and (with false) the unnamed ones.

Errors

StatusCodeMeaning
400

removeUnassigned is not true or false.

401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_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.

404unknown_install_keynot_connected

unknown_install_key, or not_connected.

409api_offintegration_offtry_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.