# OAuth2 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](https://docs.altdentifier.dev/api/http-api) for more!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.altdentifier.dev/api/oauth2-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.