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
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token you need to authenticate requests. Use this in the Authorization header. |
| token_type | String | The access token type. This will always be "Bearer". |
| expires_in | Integer | Seconds left until the access token expires. |
| refresh_token | String | The refresh token you need to obtain a new access token when this expires. |
| scope | String | Space-separated list of access token scopes. Currently, this will always be "all". |
| issued_at | String | UTC timestamp of the access token issue date. |
| expiration_date | String | UTC timestamp of the access token expiration date. |
| message | String | A 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
| Parameter | Type | Description |
|---|---|---|
| token_type | String | The access token type. This will always be "Bearer". |
| expires_in | Integer | Seconds left until the access token expires. |
| scope | String | Space-separated list of access token scopes. Currently, this will always be "all". |
| is_valid | Boolean | Whether the provided token is still valid or must be renewed. |
| issued_at | String | UTC timestamp of the access token issue date. |
| expiration_date | String | UTC timestamp of the access token expiration date. |
| message | String | A 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
| Parameter | Type | Description |
|---|---|---|
| access_token | String | The access token you need to authenticate requests. Use this in the Authorization header. |
| token_type | String | The access token type. This will always be "Bearer". |
| expires_in | Integer | Seconds left until the access token expires. |
| refresh_token | String | The refresh token you need to obtain a new access token when this expires. |
| scope | String | Space-separated list of access token scopes. Currently, this will always be "all". |
| issued_at | String | UTC timestamp of the access token issue date. |
| expiration_date | String | UTC timestamp of the access token expiration date. |
| message | String | A 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.