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" }

Make sure to replace abcdefghijklmnopqrstuvwxyz0123456789 with your access token.

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

The API gateway expects the received access token to be included in all API requests to the server, in a header that looks like the following:

Authorization: abcdefghijklmnopqrstuvwxyz0123456789

The API gateway also accepts the following header formats:

Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789

X-Access-Token: abcdefghijklmnopqrstuvwxyz0123456789

X-Access-Token: Bearer abcdefghijklmnopqrstuvwxyz0123456789

Obtaining an Access Token

In order to obtain an API gateway access token, users first need to authenticate themselves with their Discord account.

The gateway will obtain the user's Discord identity, including the Discord access token. The Discord token will be retained (encrypted) by the API gateway and will be hidden to the front-end, enhancing security for the end-user.

Obtaining the access token to the API gateway is a 2-step process.

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>...

First of all, generate a new Discord login request by hitting the following gateway endpoint with your provided 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 will be redirected to the Discord login page. Upon a successful login, the callback URL will contain a new query string parameter, ?code=<TEMPORARY_TOKEN>, that will be needed for the second login phase.

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."
}

The temporary short token must then be exchanged with a full token in order to send further requests to the API gateway:

HTTP Request

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

Using this header:

Authorization: <TEMPORARY_TOKEN>

HTTP Response

The long access_token provided here must be added to all requests in order to identify the user and its authorization set. The access_token and refresh_token will only be shown in this response and will not be obtained through subsequent requests. Make sure to 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 verify the time left on your token until it must be renewed.

HTTP Request

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

Using this header:

Authorization: <ACCESS_TOKEN>

HTTP Response

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

The long access_token provided here must be added to all requests in order to identify the user and its authorization set. The access_token and refresh_token will only be shown in this response and will not be obtained through subsequent requests. Make sure to 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 consists of an atomic object, containing a success parameter (Boolean) indicating whether the token was successfully revoked.