> For the complete documentation index, see [llms.txt](https://docs.altdentifier.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.altdentifier.dev/api/oauth2-api.md).

# 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](https://altdentifier.dev/applications).

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

{% hint style="danger" %}
Note: The OAuth2 API is very basic at this time and some functionality may not work as expected. 
{% endhint %}

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

<mark style="color:blue;">`GET`</mark> `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 | <p>The scopes you are requesting. If requesting multiple, seperate by space.<br>Currently supported scopes are "read:user" and "write:integrations". </p>                                              |
| 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 | <p>The Response Type your application wants. This currently must always be set to "code", or left out if using our simplified integration flow.<br>Implicit grants are not supported at this time!</p> |

{% tabs %}
{% tab title="200 Returns our authorization page to the user" %}

```javascript
```

{% endtab %}

{% tab title="404 Returned when the client id does not exist" %}

```
```

{% endtab %}

{% tab title="500 Returned when we fuck up" %}

```
```

{% endtab %}
{% endtabs %}

### Step 2.&#x20;

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.&#x20;

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:&#x20;

## Exchange Token

<mark style="color:green;">`POST`</mark> `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.                         |

{% tabs %}
{% tab title="200 Your code was succesfully exchanged" %}

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

{% endtab %}

{% tab title="400 You provided incorrect information when exchanging your token" %}

```javascript
{"error": "Cannot grant token"}
```

{% endtab %}

{% tab title="401 Your client credentials were incorrect" %}

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

{% endtab %}
{% endtabs %}

### Step 4.&#x20;

Once you have obtained the token, you can start making requests to our API. See [HTTP API](/api/http-api.md) for more!