Modbot Docs
API

API keys

Making, using and revoking the keys that let a program use your Modbot's API.

An API key lets a program use your Modbot's API as you. You choose what each key may do, and it can never do more than you can.

Who can manage keys

Keys need the Manage API keys and webhooks permission (see roles and permissions). Anyone with it can:

  • see every key on this Modbot, whoever made it (never the key itself)
  • make keys for themselves
  • revoke any key

Keys live on Settings → API → Keys. In the web app, the Settings page only appears for people who also have Change settings. Someone with only Manage API keys and webhooks can still manage keys through the API itself, with GET, POST and DELETE on /api/api-keys.

Making a key

Open the Keys tab

Go to Settings, then the API tab, then Keys. Click Create key.

Name it

Give it a Name you will recognise later, such as the name of the bot that will use it. At most 64 characters.

Choose when it stops working

Expires is optional. Pick a date and the key stops working at the end of that day, in your browser's time zone. Leave it empty for a key that never expires.

Tick what it may do

The list shows only the permissions you hold yourself, grouped as on the Roles page. Tick at least one. Give a key only what its program needs: a bot that posts bans to a chat needs See the audit log, not Administrator.

Copy the key

Click Create. The key is shown once, with a copy button. Copy it now and store it somewhere safe, such as your bot's settings or a password manager.

The key is shown only once

Modbot keeps only a fingerprint of the key (a SHA-256 hash), so it cannot show it again. If you lose it, revoke it and make a new one.

A key looks like mbk_ followed by 43 letters, digits, - and _. The first twelve characters are kept in the clear, so the list can show which key is which.

Using a key

Send it in the Authorization header:

curl -H "Authorization: Bearer mbk_..." https://modbot.example.com/api/auth/me

GET /api/auth/me answers with the account the key belongs to, which is a quick way to check a key works. Its apiKey field names the key and lists what it may do right now (see Who is calling). See the API overview for what keys cannot do, and Errors for what a refusal looks like.

What a key may do

A key has two limits, and both apply on every request:

  1. The permissions ticked when it was made.
  2. The permissions its owner holds right now.

The key may do only what both allow. So:

  • If someone removes a permission from you, your keys lose it on their next request.
  • If your account is disabled, your keys stop working. If it is enabled again, they work again: disabling does not revoke them.
  • If your account has not linked its VRChat account, its keys do not work.

Administrator is the one special case, because it means "everything":

Your account has AdministratorThe key has AdministratorThe key may do
Yeseitherexactly what was ticked on the key
NoYeseverything your account holds now
NoNowhat both the key and your account hold

A key with Manage API keys and webhooks can make more keys. Those keys belong to the same account and can hold no more than the key that made them.

What a key's account does with a key is recorded in the audit log as done by that account, and the entry's raw data carries the key's id as apiKeyId. An entry made in the browser has none. Two things are not marked: records a key imports from a file, which keep the actor the file names, and entries Modbot writes later in the background, such as when an import finishes.

A webhook made with a key sends only what that key may see, and is turned off when the key is revoked or expires.

The key list

The list on Settings → API → Keys shows every key:

Column
NameThe name it was given.
KeyThe first twelve characters.
OwnerThe account that made it.
PermissionsWhat was ticked, by the permission's short code name (for example ViewAuditLog).
CreatedWhen it was made.
Last usedWhen a request last used it, or Never. This is updated at most once a minute, so it can be up to a minute behind.
ExpiresIts expiry, or Never.
StateActive, Expired or Revoked.

Expired and revoked keys stay in the list, greyed out.

Revoking a key

Click Revoke beside the key, then click the red Revoke that takes its place to confirm, or Cancel to back out. It cannot be undone.

A revoked key stops working on its next request. A program that is already connected notices a little later:

  • A live event WebSocket is closed with code 4003 at its next heartbeat, about every thirty seconds. See events over WebSocket.
  • A long poll that is waiting stops within a few seconds and answers 401. See long polling.

Any webhook the key made is turned off on the next delivery pass, with the reason The API key that set it up was revoked.

Revoke a key as soon as you think someone else may have it, and make a new one.

What is recorded

Making and revoking a key are recorded in the operational log, with who did it, the key's name, its first twelve characters, and (when made) its permissions and expiry. The key itself is never recorded. Individual requests made with a key are not recorded; the key's Last used time is all that changes.

Making keys through the API

The same actions are on the API, for a program holding a key with Manage API keys and webhooks:

Request
GET /api/api-keysEvery key, and in grantable the permissions you may put on a new one.
POST /api/api-keysMake a key for yourself.
DELETE /api/api-keys/{id}Revoke a key. Answers 204, also when it was already revoked.
POST /api/api-keys
Authorization: Bearer mbk_...
Content-Type: application/json

{ "name": "Discord bot", "permissions": ["ViewAuditLog"], "expiresAt": "2027-01-31T23:59:59Z" }

permissions takes the permission code names that GET /api/api-keys lists. expiresAt may be null for a key that never expires, and must not be in the past. The answer carries the new key in key, once, beside the list entry in apiKey.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page