> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Gérer les jetons de compte de la plateforme AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**Le jeton de compte (Account Token, anciennement appelé Platform Token)** est une « clé au niveau du compte » permettant aux développeurs de gérer par programmation les ressources de la plateforme AceDataCloud (demandes de service, identifiants API, commandes, historiques d’appels, solde, fichiers, etc.). Son rôle est similaire au Token utilisateur après une connexion côté frontend, et il n’a pas de date d’expiration par défaut ; les utilisateurs ordinaires ne peuvent gérer que leurs propres jetons, tandis que les super administrateurs peuvent gérer les jetons d’autres comptes selon leurs autorisations.

Les jetons de compte accèdent aux interfaces de la plateforme avec les autorisations actuelles du compte auquel ils appartiennent : les autorisations de base, les autorisations accordées directement et les autorisations des groupes d’utilisateurs auxquels il appartient prennent effet ensemble ; après l’ajout ou le retrait d’un groupe, la requête suivante est jugée selon les nouvelles autorisations. L’accès à des ressources spécifiques telles que les demandes et les commandes nécessite toujours une vérification d’appartenance. Les jetons de compte n’expirent pas par défaut ; veuillez les utiliser uniquement dans des environnements fiables et les conserver correctement.

> ℹ️ Cette interface appartient à l’**API de gestion de la plateforme AceDataCloud**, avec le préfixe unifié `https://platform.acedata.cloud/api/v1/`. Pour l’index complet des interfaces, consultez [Obtenir la liste des documents de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Jeton de compte vs identifiant API

Les deux types de clés les plus facilement confondus par les débutants, veuillez d’abord bien les distinguer :

| Dimension | **Jeton de compte** (ce document) | **Identifiant API (Credential)** |
| - | - | - |
| Usage | Appeler les interfaces de gestion `https://platform.acedata.cloud/**` | Appeler les interfaces métier `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo, etc.) |
| Format | `platform-v1-` + 64 chiffres hexadécimaux (76 caractères au total) | 32 chiffres hexadécimaux |
| Un compte | Généralement 1–2 jetons | 1–N jetons par demande de service |
| Point d’entrée de création | [Console Account Token](https://platform.acedata.cloud/console/platform-tokens) | [Créer un identifiant API de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| Conditions d’invalidation | Devient immédiatement invalide après suppression ; expire lorsque `expiration` n’est pas nul | Peut définir une limite de quota, une date d’expiration et lier une IP source |

Si vous souhaitez seulement appeler GPT-4.1, vous avez besoin d’un **identifiant API**, et non d’un jeton de compte.
Si vous souhaitez écrire des scripts d’automatisation pour gérer les recharges, consulter les factures mensuelles ou distribuer des identifiants en lot aux membres de l’équipe, utilisez alors un jeton de compte.

***

## Créer en un clic dans la console (recommandé)

1. Connectez-vous à [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. Accédez à la barre latérale → « Développeur » → « [Account Token](https://platform.acedata.cloud/console/platform-tokens) ».
3. Cliquez sur le bouton « Créer » en haut à droite pour obtenir immédiatement un jeton `platform-v1-...`, **cliquez sur le bouton de copie pour l’enregistrer dans votre gestionnaire de mots de passe**.

![Console Account Token](https://cdn.acedata.cloud/6g86oz.png)

> ⚠️ Actuellement, les réponses de création, de liste et de détail renvoient toutes le jeton en clair. Veuillez traiter toute la réponse comme un secret, ne l’écrivez pas dans les journaux, les plateformes d’analyse ou le stockage persistant frontend ; les clients ne doivent pas non plus dépendre du maintien à long terme du retour en clair dans la liste.

***

## Créer un jeton de compte avec l’API

### Vue d’ensemble de l’interface

| Élément | Contenu |
| - | - |
| Méthode | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Authentification | ✅ Tout jeton de compte existant ou JWT de session de navigateur |
| Body | `application/json` (un objet vide `{}` peut être transmis) |

### Explication de l’authentification (problème de l’œuf et de la poule)

> Comment obtenir le premier jeton ? La réponse est de **passer par la console** — après la connexion dans le navigateur, la console appelle `POST /platform-tokens/` avec l’authentification JWT et vous délivre le premier jeton.
> Ensuite, vous pouvez utiliser n’importe quel jeton `platform-v1-...` existant pour en créer davantage.

Format de l’en-tête de requête :

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
Content-Type: application/json
```

### Exemple de requête

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/platform-tokens/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'
```

### Réponse (HTTP 201)

```json theme={null}
{
  "id": "3264f1aa-cbe1-4e2c-a434-95adba4f8304",
  "token": "platform-v1-<REDACTED>",
  "expiration": null,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "created_at": "2026-04-26T15:50:11.123456Z",
  "updated_at": "2026-04-26T15:50:11.123456Z",
  "used_at": null
}
```

### Description des champs

| Champ | Type | Description |
| - | - | - |
| `id` | UUID | Clé primaire du jeton, utilisée lors de la suppression / de la consultation des détails |
| `token` | string | Jeton de compte en clair. Format `platform-v1-` + 64 chiffres hexadécimaux (76 caractères au total), doit être traité comme un secret |
| `expiration` | int \| null | Heure d’expiration (horodatage en secondes). `null` indique qu’aucune date d’expiration n’est définie |
| `user_id` | UUID | ID de l’utilisateur propriétaire. C’est également la valeur du paramètre `?user_id=` qui doit être transmise dans toutes les interfaces de liste ultérieures |
| `created_at` | datetime (ISO8601) | Heure de création |
| `updated_at` | datetime (ISO8601) | Heure de mise à jour |
| `used_at` | datetime \| null | Heure de la dernière utilisation pour l’authentification. Si jamais utilisé, la valeur est `null`, ce qui peut servir à détecter les « jetons zombies » |

***

## Obtenir la liste des jetons de compte

### Vue d’ensemble de l’interface

| Élément | Contenu |
| - | - |
| Méthode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Authentification | ✅ Jeton de compte requis |

### Paramètre de requête obligatoire

> ⚠️ **Vous devez inclure `?user_id=<your_user_id>`**. Raison : l’interface de liste effectue une vérification d’autorisation **objet par objet** sur les résultats paginés ; sans `user_id`, le premier objet ne vous appartenant pas sera refusé et renverra `403 permission_denied`.

Comment obtenir `user_id` :

1. Ouvrez [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile) dans le navigateur ; le UUID complet s’affiche en haut de la page.
2. Ou remplissez directement la valeur du champ `user_id` renvoyée par `POST /platform-tokens/`.

### Paramètres de requête

| Paramètre | Obligatoire | Type | Description |
| - | - | - | - |
| `user_id` | ✅ | UUID | ID utilisateur du compte actuel |
| `limit` | ❌ | int | Nombre d’éléments par page, 10 par défaut, 100 au maximum |
| `offset` | ❌ | int | Décalage |
| `ordering` | ❌ | string | Champ de tri, `-created_at` par défaut |

### Exemple de requête

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b&limit=5' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

### Réponse (HTTP 200)

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "51c575a2-801c-4211-bc47-711452a8c8c9",
      "token": "platform-v1-<REDACTED>",
      "expiration": null,
      "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
      "created_at": "2026-04-26T15:41:32.761705Z",
      "updated_at": "2026-04-26T15:41:32.761726Z",
      "used_at": null
    }
  ]
}
```

> La réponse paginée de cette interface utilise `count` + `items`. D’autres interfaces de plateforme peuvent utiliser des structures différentes ; veuillez vous référer à la documentation correspondante et aux réponses réelles.

***

## Obtenir les détails d’un jeton de compte

| Élément | Contenu |
| - | - |
| Méthode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**sans barre oblique finale**） |
| Authentification | ✅ Accessible uniquement au créateur du jeton ou au superadministrateur |

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/51c575a2-801c-4211-bc47-711452a8c8c9' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

La structure retournée est identique à celle d’un élément de la liste, `HTTP 200`.

***

## Supprimer un jeton de compte

| Élément | Contenu |
| - | - |
| Méthode | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**sans barre oblique finale**） |
| Authentification | ✅ Seul le créateur du jeton ou le superadministrateur peut le supprimer |

```shell theme={null}
curl -X DELETE 'https://platform.acedata.cloud/api/v1/platform-tokens/3264f1aa-cbe1-4e2c-a434-95adba4f8304' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

* En cas de succès, retourne `HTTP 204 No Content`, sans corps de réponse.
* Après suppression, ce jeton devient **immédiatement invalide**, et tous les services qui l’utilisent recevront aussitôt un `401`.
* Interroger à nouveau cet `id` retournera `404`.

> ⚠️ La suppression est irréversible. Si vous soupçonnez une fuite du jeton, vous pouvez **d’abord en créer un nouveau, basculer le côté métier, puis supprimer l’ancien**.

***

## Opérations non prises en charge

| Opération | HTTP | Description |
| - | - | - |
| Modification par `PATCH` | 405 | Après sa création, un jeton de compte **ne prend en charge aucune modification de champ**. Pour des usages comme le renommage, supprimez-le puis recréez-le |
| Remplacement par `PUT` | 405 | Idem |

***

## Référence rapide des codes d’erreur

| HTTP | `code` | Cause fréquente |
| - | - | - |
| 401 | `not_authenticated` | En-tête `Authorization` absent, ou jeton supprimé |
| 403 | `permission_denied` | Interface de liste sans `?user_id=`, ou accès aux détails du jeton d’une autre personne |
| 404 | `not_found` | L’`id` n’existe pas ou a été supprimé |
| 405 | `method_not_allowed` | `PATCH`/`PUT` envoyé à l’interface de détails |

Format unifié des réponses d’erreur :

```json theme={null}
{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied",
  "trace_id": "0a88956213edf6e62b71695ee2df0eff"
}
```

Lors du diagnostic, fournissez le `trace_id` au service client ou incluez-le dans le ticket afin de localiser rapidement les journaux.

***

## Exemple de code complet

### Python

```python theme={null}
import os
import requests

BASE = "https://platform.acedata.cloud/api/v1"
PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {PLATFORM_TOKEN}",
    "content-type": "application/json",
}

# 1. 创建新令牌
created = requests.post(f"{BASE}/platform-tokens/", headers=headers, json={}).json()
print("新令牌：", created["token"])
print("UserID：", created["user_id"])

# 2. 列表
listing = requests.get(
    f"{BASE}/platform-tokens/",
    headers=headers,
    params={"user_id": USER_ID, "limit": 50},
).json()
print(f"共 {listing['count']} 枚令牌")

# 3. 删除（注意末尾无斜杠）
resp = requests.delete(f"{BASE}/platform-tokens/{created['id']}", headers=headers)
assert resp.status_code == 204, resp.text
```

### Node.js

```javascript theme={null}
const BASE = 'https://platform.acedata.cloud/api/v1'
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'

const headers = {
  accept: 'application/json',
  authorization: `Bearer ${PLATFORM_TOKEN}`,
  'content-type': 'application/json',
}

// 创建
const created = await fetch(`${BASE}/platform-tokens/`, {
  method: 'POST',
  headers,
  body: '{}',
}).then((r) => r.json())

// 列表
const url = new URL(`${BASE}/platform-tokens/`)
url.searchParams.set('user_id', USER_ID)
const listing = await fetch(url, { headers }).then((r) => r.json())
console.log(`共 ${listing.count} 枚令牌`)

// 删除（末尾无斜杠）
await fetch(`${BASE}/platform-tokens/${created.id}`, { method: 'DELETE', headers })
```

***

## Utilisation dans d’autres API de plateforme

Placez directement `platform-v1-...` dans l’en-tête `Authorization: Bearer ...` pour appeler toute interface de plateforme nécessitant une authentification :

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/applications/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

> Ils sont **entièrement différents** des identifiants API hexadécimaux à 32 caractères utilisés par les interfaces métier `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo, etc.). Ne les mélangez pas — utiliser un jeton de compte dans une interface métier produira un `401`, et inversement.

***

## Interfaces associées

* [Obtenir la liste des demandes de services de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — utiliser le jeton de compte pour voir les services auxquels on a fait une demande
* [Créer des identifiants API pour la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — utiliser le jeton de compte pour émettre des identifiants à 32 caractères destinés aux API métier
* [Obtenir les enregistrements d’appels API de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — vérifier la facturation et résoudre les erreurs
* [Obtenir la liste des commandes de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — consulter l’historique des recharges


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.