Access keys

The REST API is authenticated with a bearer key. Keys are created by the assistant’s owner, in the product, and belong to exactly one assistant.

Creating one

In the assistant’s Places tab, open Your own software and create a key.

mb_live_9f3c1d7a0b5e2846...

The key list afterwards shows each key’s prefix, when it was created and when it was last used, which is enough to tell two keys apart and to spot one nothing is using any more.

What a key can do

A key can send messages to its own assistant and nothing else. The lookup binds the key’s digest and the assistant id in one query, so a valid key for assistant A is not a key for assistant B.

The assistant must be live. A draft or paused assistant answers 409 Conflict — deliberately a status code, not a polite sentence, because a program cannot tell “we’re not available” from a real answer but it can branch on a 409.

Keys are server-to-server

The API is designed on that assumption. A cross-site POST from a browser is refused by the origin check before the key is even looked at, and there is no CORS preflight allowance for it. If you want chat on your website, use the website bubble — no key required.

One error for every key problem

A missing key, a malformed key, an unknown key and someone else’s key all come back as the same 401 with the same message:

{ "error": { "tag": "Unauthenticated", "message": "Missing or invalid API key." } }

That is intentional. A caller probing keys learns nothing from which of the four it hit.

Rotating and revoking

Delete a key and it stops working immediately. To rotate without downtime: create the new key, deploy it, confirm the old key’s “last used” has stopped moving, then delete the old key.

Next: Send a message.