OAuth2 API

Interacting with AltDentifier's OAuth API

Getting Started

This guide/documentation will assume you have already created an application for AltDentifier. If you have not, click here.

While we recommend using a library to deal with OAuth, we will explain some parts of the OAuth integration for manual implementation.

Note: The OAuth2 API is very basic at this time and some functionality may not work as expected.

OAuth2 for Integrations

If the application you are creating is an AltDentifier integration, meaning that your application will get linked to someone's Discord server, you do not need to implement OAuth in full. You can prompt users to add your integration with the following link format:

https://altdentifier.com/oauth2/authorize?client_id=yourclientid&scope=write:integrations

Integrating OAuth2

Step 1.

To get started, make sure you have your Client ID and Client Secret closeby. To start the authorization process, you must redirect your users to our authorization page, which is as follows:

Get Authorize

GET https://altdentifier.com/oauth2/authorize

The user Authorization page for OAuth

Query Parameters

Name	Type	Description
guild_id	string	Directly point users to a guild, only if you are using the write:integrations scope.
state	string	A state token used to verify the request is made on your applications behalf. This value will be returned to you when redirecting to your redirect_uri.
scope	string	The scopes you are requesting. If requesting multiple, seperate by space. Currently supported scopes are "read:user" and "write:integrations".
redirect_uri	string	The URL to redirect your users to after they authorize your application. Optional if using the simplified integration flow.
client_id	string	The Client ID for your application
response_type	string	The Response Type your application wants. This currently must always be set to "code", or left out if using our simplified integration flow. Implicit grants are not supported at this time!

200 Returns our authorization page to the user

404 Returned when the client id does not exist

500 Returned when we fuck up

Step 2.

Once the user authorizes your application, the user will be redirected to the redirect_uri you set when starting authorization. The "code" and "state" query arguments will be added. Make sure to verify your state with the one you generated earlier. Store the "code" argument in a variable.

Step 3.

Once you have obtained the OAuth 2 code, you cannot use it yet. To start making requests, you need to exchange your code for a Bearer Token. To do this, make the following request:

Exchange Token

POST https://altdentifier.com/oauth2/token

Exchange the OAuth code for a Bearer Token

Request Body

Name	Type	Description
code	string	The code you received on your Redirect URI.
scope	string	The scopes you requested earlier. Optional, you can use this to check if the user altered the scopes.
redirect_uri	string	The Redirect URI you redirected the user to earlier.
grant_type	string	Must always be "authorization_code"
client_secret	string	Your applications client secret. You can also use the HTTP Auth "password" field.
client_id	string	Your applications client id. You can also use the HTTP Auth "username" field.

200 Your code was succesfully exchanged

{"access_token": "blablatoken", "token_type": "Bearer",
 "expires_in": 604800, "refresh_token": "blablarefreshtoken",
 "scope": "read:user"}

400 You provided incorrect information when exchanging your token

{"error": "Cannot grant token"}

401 Your client credentials were incorrect

{"error": "Provided client credentials are incorrect"}

Step 4.

Once you have obtained the token, you can start making requests to our API. See HTTP API for more!