Authentication

Authenticated requests send a token in one of two headers, depending on whether you're acting as a user or a bot:

User-Auth: <token>
Bot-Auth: <token>

(Authorization: User <token> and Authorization: Bot <token> work the same way.)

Where tokens come from

Your account's User-Auth token and a bot's Bot-Auth token are both shown on the site itself (account settings, and the bot's own settings page after submission) rather than issued by an API call. There's no public endpoint for exchanging Discord OAuth2 credentials for a token, POST /auth/login/discord-oauth2 exists and is documented in the endpoint reference, but it's restricted to the official site and its own client protocol, it isn't a general-purpose login flow third-party integrations can use.

Scoped sessions

If you want to hand a token to something with narrower permissions than your full account, create a scoped session instead of sharing your own token directly.

POST /{target_type}/{target_id}/sessions

Requires the Manage API Sessions permission on the target entity (bot, server, team, or pack). Body:

{
  "name": "My integration",
  "type": "api",
  "perm_limits": ["edit_bots"],
  "expiry": 604800
}

Field	Type	Notes
`name`	string	A label so you can recognize the session later.
`type`	string	Must be `api`, login sessions can't be created through this endpoint.
`perm_limits`	string[]	The permissions the session is allowed to use. Empty is only allowed if you hold the `owner` permission on the target, in which case the session gets full access.
`expiry`	number	How long the session lasts, in seconds.

The response includes the session's token, only shown once, there's no way to read it back afterward.

{
  "target_id": "1234567890",
  "token": "...",
  "session_id": "..."
}

Managing sessions

GET    /{target_type}/{target_id}/sessions
DELETE /{target_type}/{target_id}/sessions/{session_id}

Listing requires View API Sessions, revoking requires Manage API Sessions. A listed session never includes its token, only its name, type, permission limits, and expiry, so losing track of a token means creating a new session rather than looking the old one up.

Testing a token

POST /auth/test

Send whichever auth header you want to check. A valid token gets back the resolved identity (target_type and target_id) it authenticates as; an invalid or expired one gets a 401.

Where tokens come from

Scoped sessions

Managing sessions

Testing a token

On this page