Skip to content
MyEscapeRoomDocs
Esc

    Type to search. Use the arrow keys and Enter to open a result.

    API keys

    Create a key, choose what it may do, restrict where it can be used.

    Last updated

    A venue API key lets your own website or server act for your venue through the Embed API: list your rooms, read free sessions, create and look up bookings, and sell gift vouchers. Every key starts with mer_, so a leaked one is easy to recognise in a code scan.

    A key belongs to one venue. It can only see and change that venue's rooms, bookings and vouchers. If your company has several venues, create keys separately for each one, from that venue's dashboard.

    Who can manage keys#

    Owners and admins. The API page is not shown to hosts, and the API refuses a host who tries to create, change or revoke a key. The same people manage webhooks, which live on the same page. See Team & roles for what each role can do.

    Create a key#

    The API page: your keys, with the Create key button at the top right.
    The API page with the Keys table, Allowed origins and Webhooks panels

    1. Open the API page

      Go to DashboardSetupAPI and choose Create key.

    2. Name it

      Give the key a name that says where it will live, such as Website or Booking server. A name is required and can be up to 60 characters. You cannot rename a key later.

    3. Choose its permissions

      All switches are off by default. Leave them off unless the key is used from your own server. They are explained under Permissions below.

    4. Copy the key

      Choose Create. The new key appears at the top of the page. Copy it now: it is shown once and cannot be shown again, because MyEscapeRoom stores only a hash of it. It stays on screen until you choose Done, so a stray click will not lose it.
    The Create key dialog.
    The Create key dialog with a name field and two permission switches
    The new key is shown once. Copy it before you choose Done.
    The Your new key notice showing the full key with Copy and Done buttons

    The table afterwards shows the key's first 12 characters (mer_ and eight more) so you can recognise it, who created it and when, and when it was last used. Last used is a hint, updated at most once a minute, not an access log.

    Store the key in your server's secret manager or an environment variable, never in a repository. To use it, send it in the Authorization header, or in x-api-key:

    Use a key
    curl https://myescaperoom.eu/api/embed/rooms \
  -H "Authorization: Bearer $MER_API_KEY"

    See Authentication & errors for the details.

    Permissions#

    Every key can do the everyday work of a booking flow. Three extra powers are switched on per key, from the Create key dialog or later with the switches in the Keys table. A change takes effect at once.

    PermissionWhat it adds
    May cancel after the player deadlineLets a call send asVenue: true on the cancel endpoint, which cancels a confirmed booking until the game starts, like the dashboard does. Without it, an API cancellation follows the same notice as a player's own cancellation (the more generous of the notice in force when the booking was made and the current one), and on a confirmed booking asVenue is refused with 403 API_KEY_NOT_PERMITTED. On a booking that is only a hold it is ignored.
    May manage vouchersLets the key list your gift vouchers (with their codes), sell a voucher without taking payment (collectPayment: false), cancel a voucher you sold yourself, and request the invoice of a voucher that is already active.
    May read guest detailsPuts the guests' name, email and phone, and the reason a booking was cancelled (free text that often names the guest), in the booking answers: the list, a single booking, the answer to creating a booking and the answer to cancelling one. Without it guestName, guestEmail, phone and cancellationReason are null in every booking answer, and the buyer of a voucher is left out of voucher answers too (a key that may manage vouchers still sees its buyers). Everything else about a booking stays visible, such as its status, session and amounts.

    What any key can do#

    These are the powers a key has without any of the permissions. Treat them as what a stranger holding the key could do.

    • List your venue and active rooms, and read every room's free sessions.
    • Create bookings. Each one holds a session for 15 minutes until it is paid, so someone with your key can make sessions disappear from sale for a while.
    • Read your bookings (their status, session, room and amounts) through GET /api/embed/bookings and by reference, but not the booker's name, email or phone.
    • Release an unpaid booking, and cancel a confirmed one inside the player notice (the more generous of the notice in force when it was booked and the venue's current one), when that notice lets players cancel at all.
    • Read any gift voucher by its code, sell a voucher with online payment, and cancel one that is still waiting for its payment.
    • Ask for the invoice of a booking, and of a voucher that is still unpaid.

    Without the permissions, a key cannot list vouchers, mint a voucher without payment, cancel a voucher you sold yourself, read the guests' contact details, or cancel a confirmed booking after the player notice. Today you cannot narrow a key to fewer endpoints: it either has these powers or it does not.

    Browser keys and server keys#

    Prefer calling the API from your server. Your server holds the key, your page talks to your server, and only Stripe.js talks to Stripe from the browser. The key is never visible to anyone.

    A key used in a web page is public: anyone who opens the page source can copy it. Whoever has it can do everything under What any key can do. Only do this knowingly, with a key of its own.

    A good setup is two keys: Website (browser) with all switches off, and Booking server with only the switches you need. If either leaks, you revoke only that one.

    Allowed origins#

    The Allowed origins panel lists the websites whose browsers may call the API with your keys. A request that comes from a browser on a website that is not listed is refused with 403 ORIGIN_NOT_ALLOWED before anything is done, so a booking is not even created. With no origin listed, no website's browser can call the API. Calls from your own server are not affected, because a server sends no Origin header. MyEscapeRoom's own booking widget is always allowed.

    Allowed origins, with one site added.
    The Allowed origins panel with one origin listed and an Add field

    1. Enter the origin

      Under Allowed origins, type the site as https://www.your-venue.com: the scheme and host, with no path, no query and no wildcard.

    2. Add it

      Choose Add. Add every address your site is served from, such as the version with and without www.

    3. Save

      Choose Save origins. Adding or removing an origin does nothing until you save.
    Valid origins
    https://www.your-venue.com
https://your-venue.com
http://localhost:3000
    • You can list up to 20 origins for a venue, shared by all its keys.
    • Only https is accepted, except http://localhost and http://127.0.0.1 (with any port) for development.
    • An address with a path, query, username or wildcard is refused when you add it.
    • Matching is exact, so a different port or scheme is a different origin.

    Revoke a key#

    Revoke a key as soon as you suspect it has leaked, or when the site or person using it moves on.

    1. Find the key

      Open DashboardSetupAPI and find the key in the Keys table. Check its name and its first characters.

    2. Revoke it

      Choose Revoke on its row, then Revoke again in the confirmation.
    Revoking asks for confirmation. It cannot be undone.
    The Revoke key confirmation dialog

    A revoked key stops working immediately: every call with it answers 401 UNAUTHORIZED. It stays in the table, marked Revoked, so you have a record of it. A revoked key cannot be restored or changed.

    Rotate a key#

    There is no "regenerate" button: a key's secret never changes. To rotate, replace it in four steps, so your site never goes down.

    1. Create the new key

      Create a key with the same permissions as the old one. A name such as Booking server 2026-11 tells the two apart.

    2. Deploy it

      Put the new key in your server's secret store and deploy. A key sent in a page needs the page redeployed.

    3. Check the old key is idle

      In the Keys table, look at the old key's Last used. It should stop moving. Remember it is updated at most once a minute.

    4. Revoke the old key

      Revoke it, as in the section above.

    Troubleshooting#

    What you seeLikely cause
    401 UNAUTHORIZEDNo key was sent, the key is misspelt or unknown, it was revoked, or the venue is not live. The answer does not say which.
    403 API_KEY_NOT_PERMITTEDThe call needs a permission this key lacks: May manage vouchers or May cancel after the player deadline. Switch it on for a server-side key.
    403 ORIGIN_NOT_ALLOWED, or a CORS error in the browser consoleThe page's origin is not in Allowed origins (or you did not choose Save origins). The request was refused and nothing was done. The browser may show it as a CORS error, since the refusal carries no Access-Control-Allow-Origin header. A wrong key also shows as a CORS error, because a 401 lacks that header too.
    guestName, guestEmail, phone and cancellationReason are nullThe key lacks May read guest details. Switch it on for a server-side key.
    I lost a key's secretIt cannot be recovered. Create a new key, switch your site over, and revoke the old one.
    There is no API page in the menuYour role is host, and hosts do not get the API page. Ask an owner or admin.

    Related#

    MyEscapeRoom Docs