OAuth2¶

OAuth2 is how a user grants an application access to their account. The same consent step can also install the application's bot into a guild or a group DM. Application records, client secrets, and bot tokens belong to the Applications resource.

Authorisation code grant¶

1. The application sends the user's browser to Authorise application (GET /oauth2/authorize). TEBHOS redirects the browser to the consent screen of the web app, https://tebhos.com/oauth2/authorize, forwarding every query parameter.
2. When the user approves, the web app calls Grant OAuth2 consent. TEBHOS issues an authorisation code and returns the application's callback URL with code (and state) appended.
3. The application's server exchanges the code at Exchange OAuth2 token with its client credentials and receives an access token and a refresh token.
4. The application calls Get OAuth2 user information or Get current OAuth2 authorisation with Authorization: Bearer <access_token>.

Proof Key for Code Exchange (PKCE) is supported with the S256 and plain methods. The challenge is bound to the code when the code is issued. A code_challenge without code_challenge_method is treated as plain. An exchange for a code that has a challenge must supply a matching code_verifier.

Credentials and lifetimes¶

Treat authorisation codes, client secrets, access tokens, and refresh tokens as opaque secrets. Each one is 32 random bytes encoded as base64url.

A refresh exchange consumes the presented refresh token and issues a new pair. Access tokens issued earlier stay valid until they expire.

Route authentication¶

Authorise application, Grant OAuth2 consent, and the authorisation listing routes authenticate the user with a session token. The token, introspection, and revocation routes authenticate the application with its client ID and client secret instead, and key their rate limit on the client IP address. Get OAuth2 user information and Get current OAuth2 authorisation authenticate with the OAuth2 access token.

OAuth2 scopes¶

A scope names one thing the application may read or do on the user's behalf.

TEBHOS splits a scope string on whitespace and +, drops empty parts, and collapses repeated values. An unrecognised value rejects the request with invalid_scope.

OAuth2 errors¶

OAuth2 failures use the ordinary error response. The OAuth2 error name is in message, sometimes followed by a colon and detail:

{
  "error": "400 Bad Request",
  "code": "BAD_REQUEST",
  "message": "invalid_grant"
}

A client MUST branch on the HTTP status and on the error name at the start of message, never on the rest of the text.

OAuth2 token object¶

The pair a successful token exchange returns.

Structure¶

Example¶

{
  "access_token": "M2xQb1RkY0hqTmZLc1B2WndBcUx1RWc2WXRJbk9iUmE",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "VGhpc0lzQUZha2VSZWZyZXNoVG9rZW5Gb3JEb2NzMDE",
  "scope": "email identify"
}

OAuth2 user information object¶

Structure¶

OAuth2 introspection object¶

Structure¶

An inactive result has only active: false. Every other field is present when active is true, except exp, which a refresh token never has.

Current OAuth2 authorisation object¶

Structure¶

OAuth2 application summary object¶

Structure¶

OAuth2 authorisation object¶

One application the current user has authorised.

Structure¶

An application appears while the user holds at least one live access token for it.

Authorise application¶

GET /oauth2/authorize

Starts an authorisation request. Always answers with a 302 redirect. Authentication is optional.

Query parameters¶

Response¶

Without prompt=none, the redirect goes to https://tebhos.com/oauth2/authorize with every supplied parameter forwarded. Nothing is validated yet; the consent screen validates when it calls Grant OAuth2 consent.

With prompt=none, TEBHOS tries to issue a code silently:

The error target is the supplied redirect_uri when the application has registered that exact string, and the web app URL otherwise, so this route never redirects to an arbitrary origin. The error redirect carries error and state, and no error_description.

Rate limit¶

60 requests per minute for each IP address, on the oauth:authorize bucket.

Grant OAuth2 consent¶

POST /oauth2/authorize/consent

Completes an authorisation request on behalf of the signed-in user, and installs the bot when the bot scope has a target. Requires a user session token. Returns {"redirect_to": string}, the callback URL with code and, when supplied, state.

This is the route the TEBHOS consent screen calls. A third-party application does not call it directly.

JSON body¶

guild_id and channel_id are mutually exclusive. A bot-only request without redirect_uri resolves its callback to the web app URL.

Response¶

Bot installation¶

With the bot scope and a guild_id, the caller must be the guild owner or hold Manage Guild or Administrator in that guild. A caller without Administrator can only request permission bits they hold themselves.

The bot joins the guild with the caller recorded as inviter. When a non-zero permission mask is requested, TEBHOS also creates a role named after the application with exactly that mask (colour #99AAB5, not hoisted, not mentionable, placed above the existing roles) and assigns it to the bot. The guild's sessions receive a member add. The guild's member limit and ban list are not checked for a bot installed this way.

With the bot scope and a channel_id, the caller must be a recipient of the group DM. The bot is added as a recipient and a recipient-add system message is posted. A bot that is already a recipient is left as it is.

When the installation fails, the authorisation code issued by the same request is deleted, so the caller never receives a usable code.

Rate limit¶

60 requests per minute for each IP address, on the oauth:authorize bucket.

Exchange OAuth2 token¶

POST /oauth2/token

Exchanges an authorisation code or a refresh token for an OAuth2 token object.

The body is application/x-www-form-urlencoded. The application authenticates with HTTP Basic (Authorization: Basic base64(client_id:client_secret)) or with the client_id and client_secret form fields. When both are present, each form field takes precedence over the matching Basic value.

Form body: authorisation code¶

Form body: refresh token¶

Response¶

The client is authenticated before the grant is checked. A code is deleted before the tokens are issued, so replaying a code returns invalid_grant. There is no client-credentials grant: every token is bound to a user.

Rate limit¶

120 requests per minute for each IP address, on the oauth:token bucket.

Example¶

curl -X POST https://tebhos.com/api/v1/oauth2/token \
  -u "1501314428688998182:<client_secret>" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://example.com/callback \
  -d code_verifier=<verifier>

Get OAuth2 user information¶

GET /oauth2/userinfo

Returns the OAuth2 user information object for the user the access token was issued to. Requires Authorization: Bearer <access_token> with the identify scope.

Response¶

Rate limit¶

120 requests per minute for each client, on the oauth:introspect bucket.

Introspect OAuth2 token¶

POST /oauth2/introspect

Returns an OAuth2 introspection object for one access or refresh token. The body is application/x-www-form-urlencoded, and the application authenticates as for Exchange OAuth2 token.

Form body¶

Response¶

Rate limit¶

120 requests per minute for each IP address, on the oauth:introspect bucket.

Revoke OAuth2 token¶

POST /oauth2/token/revoke

Revokes a token. The body is application/x-www-form-urlencoded, and the application authenticates as for Exchange OAuth2 token.

Form body¶

A client that revokes a refresh token MUST send token_type_hint=refresh_token, otherwise nothing matches.

Response¶

An unknown token returns 200, so the response never shows whether a token existed.

Rate limit¶

120 requests per minute for each IP address, on the oauth:introspect bucket.

Get current OAuth2 authorisation¶

GET /oauth2/@me

Returns the current OAuth2 authorisation object for the presented access token. Requires Authorization: Bearer <access_token>; no scope is needed. The user member is included only when the token holds identify.

Response¶

List OAuth2 authorisations¶

GET /oauth2/@me/authorizations

Returns the OAuth2 authorisation objects the current user has granted. Requires a user session token. The list is not paginated.

Rate limit¶

60 requests per minute for each account, on the oauth_dev:clients:list bucket.

Revoke OAuth2 authorisation¶

DELETE /oauth2/@me/authorizations/{application_id}

Revokes the current user's access tokens for one application. Requires a user session token. Returns 204, also when nothing was granted.

Path parameters¶

A bot the application installed stays in every guild and group DM it joined. The application is not notified.

Rate limit¶

120 requests per minute for each account, on the oauth:introspect bucket.

Bulk revoke OAuth2 authorisations¶

POST /oauth2/@me/authorizations/revoke

Revokes the current user's complete grant (access and refresh tokens) for several applications. Requires a user session token. Returns 204.

JSON body¶

Every application is looked up before anything is deleted, so one unknown ID returns 404 and leaves every grant untouched. A value that is not a snowflake returns 400.

Rate limit¶

120 requests per minute for each account, on the oauth:introspect bucket.