Skip to main content

Search GiselleBot's commands and docs.

Try /ban, or start with / for commands only.

Press Ctrl K anywhere in the dashboard to open this.

Authorization

HTTP Request Example(s)

GET /<API_ENDPOINT> HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: abcdefghijklmnopqrstuvwxyz0123456789
POST /<API_ENDPOINT> HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Content-Type: application/json
Authorization: abcdefghijklmnopqrstuvwxyz0123456789

{ "key": "value" }

Replace abcdefghijklmnopqrstuvwxyz0123456789 with your access token.

DisComm Bots' API endpoints go through an API gateway. The gateway uses your Discord account identifier to match your Discord user info, show your authorized features, and fetch the data you need from the Discord API.

Note

The API gateway implements a custom authentication and authorization workflow, similar to an OAuth 2.0 workflow, but not fully compliant with RFC 6749.

Warning

Throughout the login and authorization flow, the gateway calls back to the originating client to complete the login. If you build your own client, specify your callback URL when you request access to the API.

Send the access token in every API request to the server, in a header that looks like this:

Authorization: abcdefghijklmnopqrstuvwxyz0123456789

Note

You must replace abcdefghijklmnopqrstuvwxyz0123456789 with your personal access token.

The API gateway also accepts the following header formats:

Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789

X-Access-Token: abcdefghijklmnopqrstuvwxyz0123456789

X-Access-Token: Bearer abcdefghijklmnopqrstuvwxyz0123456789

Warning

Every request must also include a User-Agent header that identifies your client.

Obtaining an Access Token

To obtain an API gateway access token, you first authenticate with your Discord account.

The gateway obtains the user's Discord identity, including the Discord access token. The API gateway keeps that token encrypted and never exposes it to the front-end.

Note

The base URL for the authorization endpoints is https://gateway.cycloptux.com/auth.

Obtaining an API gateway access token takes two steps.

Authentication: Step 1

HTTP Request Example

GET /discord/login HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com

HTTP Response Example

HTTP/1.1 307 Temporary Redirect
Location: https://discord.com/api/oauth2/authorize?client_id=<APP_CLIENT_ID>...

Generate a Discord login request by calling the following gateway endpoint with your callback URL:

HTTP Request

GET https://gateway.cycloptux.com/auth/discord/login?redirect_uri=<CALLBACK_URL>

HTTP Response

Temporary Redirect. Redirecting to https://discord.com/api/oauth2/authorize?client_id=<APP_CLIENT_ID>...

The user is redirected to the Discord login page. After a successful login, the callback URL receives a new query string parameter, ?code=<TEMPORARY_TOKEN>, which you need for step 2.

Authentication: Step 2

HTTP Request Example

POST /discord/token HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <TEMPORARY_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": <ACCESS_TOKEN>,
    "token_type": "Bearer",
    "expires_in": <SECONDS_LEFT_UNTIL_EXPIRATION>,
    "refresh_token": <REFRESH_TOKEN>,
    "scope": <TOKEN_SCOPES>,
    "issued_at": <ISSUED_DATE>,
    "expiration_date": <EXPIRATION_DATE>,
    "message": "Authentication successful."
}

Exchange the temporary token for a full token before sending further requests to the API gateway:

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token

Using this header:

Authorization: <TEMPORARY_TOKEN>

HTTP Response

ParameterTypeDescription
access_tokenStringThe access token you need to authenticate requests. Use this in the Authorization header.
token_typeStringThe access token type. This will always be "Bearer".
expires_inIntegerSeconds left until the access token expires.
refresh_tokenStringThe refresh token you need to obtain a new access token when this expires.
scopeStringSpace-separated list of access token scopes. Currently, this will always be "all".
issued_atStringUTC timestamp of the access token issue date.
expiration_dateStringUTC timestamp of the access token expiration date.
messageStringA human-readable message confirming the authentication was successful.

Add the long access_token to all requests to identify the user and their authorization set. The access_token and refresh_token appear only in this response and cannot be retrieved later, so save them.

Verifying an Existing Access Token

HTTP Request Example

POST /discord/token/check HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": <SECONDS_LEFT_UNTIL_EXPIRATION>,
    "scope": <TOKEN_SCOPES>,
    "is_valid": true,
    "issued_at": <ISSUED_DATE>,
    "expiration_date": <EXPIRATION_DATE>,
    "message": "Authentication token is valid."
}

Use this endpoint to check how long your token stays valid before it must be renewed.

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token/check

Using this header:

Authorization: <ACCESS_TOKEN>

HTTP Response

ParameterTypeDescription
token_typeStringThe access token type. This will always be "Bearer".
expires_inIntegerSeconds left until the access token expires.
scopeStringSpace-separated list of access token scopes. Currently, this will always be "all".
is_validBooleanWhether the provided token is still valid or must be renewed.
issued_atStringUTC timestamp of the access token issue date.
expiration_dateStringUTC timestamp of the access token expiration date.
messageStringA human-readable message explaining whether the token is still valid or not.

Refreshing an Access Token

HTTP Request Example

POST /discord/token/refresh HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
X-Refresh-Token: <REFRESH_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": <ACCESS_TOKEN>,
    "token_type": "Bearer",
    "expires_in": <SECONDS_LEFT_UNTIL_EXPIRATION>,
    "refresh_token": <REFRESH_TOKEN>,
    "scope": <TOKEN_SCOPES>,
    "issued_at": <ISSUED_DATE>,
    "expiration_date": <EXPIRATION_DATE>,
    "message": "Authentication successful."
}

Use this endpoint to obtain a new access token from a valid refresh token.

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token/refresh

Using this header:

X-Refresh-Token: <REFRESH_TOKEN>

HTTP Response

ParameterTypeDescription
access_tokenStringThe access token you need to authenticate requests. Use this in the Authorization header.
token_typeStringThe access token type. This will always be "Bearer".
expires_inIntegerSeconds left until the access token expires.
refresh_tokenStringThe refresh token you need to obtain a new access token when this expires.
scopeStringSpace-separated list of access token scopes. Currently, this will always be "all".
issued_atStringUTC timestamp of the access token issue date.
expiration_dateStringUTC timestamp of the access token expiration date.
messageStringA human-readable message confirming the authentication was successful.

Add the long access_token to all requests to identify the user and their authorization set. The access_token and refresh_token appear only in this response and cannot be retrieved later, so save them.

Revoking an Access Token

HTTP Request Example

POST /discord/token/revoke HTTP/1.1
User-Agent: <YOUR_USER_AGENT>
Host: gateway.cycloptux.com
Accept: application/json
Authorization: <ACCESS_TOKEN>

HTTP Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

Use this endpoint to revoke an existing access token and the corresponding refresh token.

HTTP Request

POST https://gateway.cycloptux.com/auth/discord/token/revoke

Using this header:

Authorization: <ACCESS_TOKEN>

HTTP Response

The response is a single object with a success parameter (Boolean) indicating whether the token was revoked.