# Authentification

Chaque serveur Discord possède sa propre **clé API**, utilisée pour identifier et sécuriser les appels effectués vers l’API.

Ce mécanisme garantit que seules les intégrations autorisées peuvent interagir avec les données liées à votre serveur.

***

## API Token

L’accès à l’API se fait via un **API Token unique**, généré dans votre tableau de bord DiscordTop, dans la section de votre serveur :

```bash
Développeur & API → Clé API du serveur
```

Chaque serveur dispose **d’une seule clé active**, que vous pouvez régénérer à tout moment.

***

## Génération du token

Pour récupérer votre clé API, vous devez vous rendre sur votre tableau de bord puis :

1. Selectionnez le serveur concerné
2. Allez dans **Développeur & API**
3. Cliquez sur **Générer ma clé API**
4. Copiez-la et voilà.

<div><figure><img src="https://docs.discordtop.net/~gitbook/image?url=https%3A%2F%2F4036411232-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZ1O8haSztScRfu0fy1yo%252Fuploads%252FUl5pZo9oSipMeZtQvASe%252FSans%2520titre-1.png%3Falt%3Dmedia%26token%3De4601f48-f304-431e-a5ea-0d23db95fc46&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=df3bcf1e&#x26;sv=2" alt=""><figcaption></figcaption></figure> <figure><img src="https://docs.discordtop.net/~gitbook/image?url=https%3A%2F%2F4036411232-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FZ1O8haSztScRfu0fy1yo%252Fuploads%252FuvzIpASK34fDw2bh8x78%252FSans%2520titre-1.png%3Falt%3Dmedia%26token%3D02fd1c36-464f-4d6a-8fff-e9c324768cc5&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=721aefab&#x26;sv=2" alt=""><figcaption></figcaption></figure></div>

***

## Transmission du token

L’API DiscordTop utilise un **système d’authentification par token**.\
Pour des raisons de sécurité et de compatibilité avec les standards modernes, **le token doit désormais être envoyé dans les headers** sous la forme suivante :

```
Authorization: Bearer VOTRE_API_TOKEN
```

***

### Méthode recommandée

#### **Header HTTP standard**

```http
Authorization: Bearer VOTRE_API_TOKEN
```

#### Exemple :

```http
GET https://api.discordtop.net/v7/vote-check?discord_id=123456789
Authorization: Bearer dtop_xxxxxxxxxxxxx
Accept-Language: fr
```

***

## Méthodes alternatives (compatibilité)

Les formats ci-dessous restent supportés temporairement, mais **sont dépréciés** et ne doivent plus être utilisés pour de nouvelles intégrations :

#### 1) Header alternatif

```
x-api-token: VOTRE_API_TOKEN
```

#### 2) Query string (déprécié)

```
?api_token=VOTRE_API_TOKEN
```

***

## Exemple complet d’appel (format recommandé)

```http
GET https://api.discordtop.net/v7/vote-check?discord_id=123456789
Authorization: Bearer dtop_abcdef123456
Accept-Language: fr
```

Réponse :

```json
{
  "ok": true,
  "has_voted": true,
  "cooldown_remaining_seconds": 0
}
```

***

## ⚠️ **Sécurité**

#### Ne partagez jamais votre clé API

Ne l’exposez pas dans :

* le front-end de votre site
* des dépôts publics (GitHub, GitLab…)
* des screenshots ou vidéos publiques

{% hint style="danger" %}
Toutes les personnes ayant la permission `ADMINISTRATOR` sur votre serveur peut y avoir accès, veillez à bien vérifier les autorisations de vos équipes !
{% endhint %}

#### Stockez-la dans des variables d’environnement

Exemples :

```bash
DISCORDTOP_API_TOKEN="dtop_xxxxxxxx"
```

#### Régénérez la clé en cas de doute

Depuis le tableau de bord, vous pouvez :

* régénérer la clé
* invalider immédiatement toute ancienne clé
* entraîner automatiquement un rafraîchissement côté API

{% hint style="info" %}
Attention, pensez à changer votre variable d'environnement dès la génération d'une nouvelle clé. Auquel cas, les requêtes échoueront directement (dès la nouvelle génération).
{% endhint %}

#### Une clé = un serveur

La clé ne donne accès **qu’aux données du serveur Discord associé**.

## Erreurs liées à l’authentification

En cas de problème d’authentification, l’API renvoie :

### `INVALID_API_TOKEN`

```json
{
  "ok": false,
  "error": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid."
}
```

```json
{
  "ok": false,
  "error": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid."
}
```

Causes possibles :

* Token incorrect
* Token expiré ou régénéré
* Token manquant
* Token associé à un autre serveur Discord

### `API_NOT_SET`

```json
{
  "ok": false,
  "error": "API_NOT_SET",
  "message": "The API token is not set correctly.",
}
```

Cause : aucune clé valide n'a pu permettre l'identification de votre serveur Discord

La liste complète des erreurs se trouve ici :\
➡️ [*Erreurs & Codes de réponse*](https://docs.discordtop.net/api-reference/concepts-cles/erreurs-and-codes-de-reponse)