Authentication

Which token goes where. To make a token, see Applications and tokens. To protect it, see Keeping tokens safe.

Bot tokens

Every application has one bot token. Send it in the x-bot-token header on every REST request:

curl https://api.zrzur.com/users/@me -H "x-bot-token: YOUR_BOT_TOKEN"

The gateway takes the same token, either in its first message (Authenticate) or as ?token= in the URL. See Gateway.

Which header does what

If both a bot token and a session token are sent, the bot token is used. A token that is missing, wrong, or belongs to a suspended bot gets 401 with the error type InvalidSession.

Interaction and webhook tokens

• Interaction tokens come with each InteractionCreate event. They are valid for 15 minutes and only for that interaction's callback, edits and follow-ups. No header is needed: the token is part of the path.
• Webhook tokens belong to one webhook and start with zrzur_wh_. Whoever has the webhook URL can post to its channel, so treat it like a bot token. It is shown once, when it is made; a lost one can only be replaced.

Bots and their owners

Creating, editing, resetting and deleting a bot is done by its owner in the Developer Portal, with the owner's own login. A bot token cannot manage applications. Deleting a bot cannot be undone, so the owner confirms it again with their password, authenticator code or recovery code.

DELETE /bots/{bot_id}

Delete Bot. Delete a bot by its id. Requires a validated MFA ticket (X-MFA-Ticket) created by the bot owner with their password, authenticator code or recovery code.

Not available to bots.

Rate limit: bots, 10 / 10 s

GET /bots/{bot_id}

Fetch Bot. Fetch details of a bot you own by its id. A bot may fetch itself (with its own id) to read its settings, such as the privileged intents its owner switched on.

Rate limit: bots, 10 / 10 s

PATCH /bots/{bot_id}

Edit Bot. Edit bot details by its id.

Not available to bots.

Rate limit: bots, 10 / 10 s

POST /bots/{bot_id}/token/reset

Reset Bot Token. Makes a new token for the bot; the old one stops working at once and the bot is signed out everywhere. The new token is in this response only: Zrzur keeps just a hash and can't show it again. Requires a validated MFA ticket (X-MFA-Ticket) created by the bot owner with their password, authenticator code or recovery code.

Rate limit: bots, 10 / 10 s

GET /bots/{target}/commands

Fetch Public Bot Commands. The global commands a bot registered, for its page in Discover and its profile, and for the command list in a DM with it. Works for public bots, for the owner, and for anyone who has a DM with the bot. Commands limited to one server are never listed here. A public bot's list is cached for a minute; registering or changing a command through the API shows at once.

Rate limit: bots, 10 / 10 s

DELETE /bots/{target}/interactions/endpoint

Remove Interactions Endpoint. Interactions go back to the gateway.

Not available to bots.

Rate limit: bots, 10 / 10 s

PUT /bots/{target}/interactions/endpoint

Set Interactions Endpoint. Interactions go to this HTTPS address from now on, instead of the gateway. Make a signing secret first. The address gets two requests before it is saved: one with a wrong signature, which it must refuse, and a signed Ping, which it must answer with {"type":"Pong"}, in either order. Requires a validated MFA ticket (X-MFA-Ticket) created by the bot owner: this address receives what people enter into the bot.

Not available to bots.

Rate limit: bots, 10 / 10 s

POST /bots/{target}/interactions/secret

New Interactions Signing Secret. Makes the secret your server uses to check X-Zrzur-Signature; the previous one stops working at once. It is in this response only. Requires a validated MFA ticket (X-MFA-Ticket) created by the bot owner.

Not available to bots.

Rate limit: bots, 10 / 10 s

GET /bots/{target}/invite

Fetch Public Bot. Fetch details of a public (or owned) bot by its id: its profile, the permissions it asks for, whether it is verified, how many servers it is in and, if its owner chose to show it, who made it.

Rate limit: bots, 10 / 10 s

POST /bots/{target}/invite

Invite Bot. Invite a bot to a server or group by its id.`

Not available to bots.

Permissions: Channel:InviteOthers · Rate limit: bots, 10 / 10 s

GET /bots/{target}/verification

Bot verification state. Whether the bot is verified and the latest request. Owner only.

Rate limit: bots, 10 / 10 s

POST /bots/{target}/verification

Apply for verification. Ask Zrzur to verify your bot, and to approve the privileged intents it needs past 100 servers. Links to its privacy policy and terms are required, https only, and also go on the bot. One open request at a time; after a denial you can apply again a week later.

Not available to bots.

Rate limit: bots, 10 / 10 s

GET /bots/@me

Fetch Owned Bots. Fetch all of the bots that you have control over.

Not available to bots.

Rate limit: bots, 10 / 10 s

POST /bots/create

Create Bot. Create a new bot.

Not available to bots.

Rate limit: bots, 10 / 10 s

OAuth2

Signing people in to your website, and install links, are on the OAuth2 page.