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

# Verwaltung von AceDataCloud-Plattformkonto-Token (Account Token)

> Platform API guide - Ace Data Cloud

**Konto-Token (Account Token, früher Platform Token genannt)** sind „Schlüssel auf Kontoebene“, mit denen Entwickler AceDataCloud-Plattformressourcen (Serviceanträge, API-Anmeldedaten, Bestellungen, Aufrufprotokolle, Guthaben, Dateien usw.) programmatisch verwalten können. Ihre Funktion ähnelt dem Benutzer-Token nach einer Frontend-Anmeldung und sie haben standardmäßig keine Ablaufzeit; normale Benutzer können nur ihre eigenen Token verwalten, Superadministratoren können Token anderer Konten entsprechend ihren Berechtigungen verwalten.

Konto-Token greifen mit den aktuellen Berechtigungen des zugehörigen Kontos auf Plattform-Schnittstellen zu: Grundberechtigungen, direkt gewährte Berechtigungen und Berechtigungen der zugehörigen Benutzergruppe werden zusammengeführt und wirksam; nach dem Beitritt zu oder dem Entfernen aus einer Gruppe wird die nächste Anfrage anhand der neuen Berechtigungen beurteilt. Der Zugriff auf konkrete Ressourcen wie Anträge und Bestellungen erfordert weiterhin eine Zuordnungsprüfung. Konto-Token laufen standardmäßig nicht ab. Verwenden Sie sie daher nur in vertrauenswürdigen Umgebungen und bewahren Sie sie sicher auf.

> ℹ️ Diese Schnittstelle gehört zur **AceDataCloud Plattformverwaltungs-API** und verwendet einheitlich das Präfix `https://platform.acedata.cloud/api/v1/`. Den vollständigen Schnittstellenindex finden Sie unter [AceDataCloud-Plattformdokumentliste abrufen](https://platform.acedata.cloud/documents/platform-document-list).

## Konto-Token vs. API-Anmeldedaten

Die zwei Arten von Schlüsseln, die Anfänger am leichtesten verwechseln. Bitte unterscheiden Sie sie zuerst klar:

| Dimension | **Konto-Token** (dieses Dokument) | **API-Anmeldedaten (Credential)** |
| - | - | - |
| Zweck | Aufruf von Verwaltungsschnittstellen unter `https://platform.acedata.cloud/**` | Aufruf von Geschäftsschnittstellen unter `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo usw.) |
| Format | `platform-v1-` + 64-stelliges Hexadezimalformat (insgesamt 76 Zeichen) | 32-stelliges Hexadezimalformat |
| Ein Konto | In der Regel 1–2 Token | 1–N Token pro Serviceantrag |
| Erstellungseinstieg | [Account-Token-Konsole](https://platform.acedata.cloud/console/platform-tokens) | [AceDataCloud-Plattform-API-Anmeldedaten erstellen](https://platform.acedata.cloud/documents/platform-credential-create) |
| Ungültigkeitsbedingungen | Nach dem Löschen sofort ungültig; bei nicht leerem `expiration` bei Ablauf ungültig | Es können Obergrenzen für Kontingente, Ablaufzeiten und Quell-IP-Bindungen festgelegt werden |

Wenn Sie nur GPT-4.1 aufrufen möchten, benötigen Sie **API-Anmeldedaten**, keine Konto-Token.
Wenn Sie Automatisierungsskripte zur Verwaltung von Aufladungen schreiben, monatliche Rechnungen einsehen oder Anmeldedaten stapelweise an Teammitglieder verteilen möchten, verwenden Sie Konto-Token.

***

## Mit einem Klick in der Konsole erstellen (empfohlen)

1. Melden Sie sich bei [https://platform.acedata.cloud](https://platform.acedata.cloud) an.
2. Gehen Sie in der Seitenleiste zu → „Entwickler“ → „[Account Token](https://platform.acedata.cloud/console/platform-tokens)“.
3. Klicken Sie oben rechts auf die Schaltfläche „Erstellen“, um sofort einen `platform-v1-...`-Token zu erhalten, und **klicken Sie auf die Kopierschaltfläche, um ihn im Passwortmanager zu speichern**.

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

> ⚠️ Die aktuellen Antworten für Erstellung, Liste und Details geben alle den Token im Klartext zurück. Behandeln Sie die gesamte Antwort als Geheimnis und schreiben Sie sie nicht in Protokolle, Analyseplattformen oder Frontend-Persistenzen; Clients sollten sich auch nicht darauf verlassen, dass die Liste langfristig Klartext zurückgibt.

***

## Konto-Token über die API erstellen

### Schnittstellenübersicht

| Element | Inhalt |
| - | - |
| Methode | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Authentifizierung | ✅ Beliebiger vorhandener Konto-Token oder JWT der Browser-Anmeldesitzung |
| Body | `application/json` (ein leeres Objekt `{}` kann übergeben werden) |

### Hinweise zur Authentifizierung (Henne-Ei-Problem)

> Woher kommt der erste Token? Die Antwort ist: **über die Konsole** – nach der Browser-Anmeldung ruft die Konsole mit JWT-Authentifizierung `POST /platform-tokens/` auf und stellt Ihnen den ersten Token aus.
> Danach können Sie mit jedem vorhandenen `platform-v1-...`-Token weitere Token erstellen.

Format der Anfrage-Header:

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

### Anfragebeispiel

```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 '{}'
```

### Antwort (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
}
```

### Feldbeschreibung

| Feld | Typ | Beschreibung |
| - | - | - |
| `id` | UUID | Primärschlüssel des Tokens, wird beim Löschen / Abrufen von Details verwendet |
| `token` | string | Klartext des Konto-Tokens. Format `platform-v1-` + 64-stelliges Hexadezimalformat (insgesamt 76 Zeichen), muss als Geheimnis behandelt werden |
| `expiration` | int \| null | Ablaufzeit (Zeitstempel auf Sekundenebene). `null` bedeutet, dass keine Ablaufzeit festgelegt wurde |
| `user_id` | UUID | ID des zugehörigen Benutzers. Dies ist auch der Wert des Parameters `?user_id=`, der für alle nachfolgenden Listenschnittstellen übergeben werden muss |
| `created_at` | datetime (ISO8601) | Erstellungszeit |
| `updated_at` | datetime (ISO8601) | Aktualisierungszeit |
| `used_at` | datetime \| null | Zeitpunkt der letzten Verwendung zur Authentifizierung. Bei noch nie verwendeten Token `null`; kann zum Erkennen von „Zombie-Token“ verwendet werden |

***

## Konto-Token-Liste abrufen

### Schnittstellenübersicht

| Element | Inhalt |
| - | - |
| Methode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Authentifizierung | ✅ Konto-Token erforderlich |

### Obligatorischer Abfrageparameter

> ⚠️ **`?user_id=<your_user_id>` muss angegeben werden**. Grund: Die Listenschnittstelle führt für die Paginierungsergebnisse **objektweise** Berechtigungsprüfungen durch. Wenn `user_id` nicht angegeben wird, wird das erste Objekt, das nicht Ihnen gehört, abgelehnt und `403 permission_denied` zurückgegeben.

So erhalten Sie die `user_id`:

1. Öffnen Sie im Browser [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile); oben auf der Seite wird die vollständige UUID angezeigt.
2. Oder füllen Sie direkt das Feld `user_id` aus dem Rückgabewert von `POST /platform-tokens/` ein.

### Abfrageparameter

| Parameter | Erforderlich | Typ | Beschreibung |
| - | - | - | - |
| `user_id` | ✅ | UUID | Benutzer-ID des aktuellen Kontos |
| `limit` | ❌ | int | Anzahl pro Seite, Standardwert 10, maximal 100 |
| `offset` | ❌ | int | Versatz |
| `ordering` | ❌ | string | Sortierfeld, Standardwert `-created_at` |

### Anfragebeispiel

```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}"
```

### Antwort (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
    }
  ]
}
```

> Die paginierte Antwort dieser Schnittstelle verwendet `count` + `items`. Andere Plattform-Schnittstellen können andere Strukturen verwenden; maßgeblich sind die jeweilige Dokumentation und die tatsächliche Antwort.

***

## Kontotoken-Details abrufen

| Element | Inhalt |
| - | - |
| Methode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**kein Schrägstrich am Ende**） |
| Authentifizierung | ✅ Nur der Tokenersteller oder ein Superadministrator kann darauf zugreifen |

```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}"
```

Die Rückgabestruktur entspricht einem Listenelement, `HTTP 200`.

***

## Kontotoken löschen

| Element | Inhalt |
| - | - |
| Methode | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**kein Schrägstrich am Ende**） |
| Authentifizierung | ✅ Nur der Tokenersteller oder ein Superadministrator kann löschen |

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

* Bei Erfolg wird `HTTP 204 No Content` ohne Antwortkörper zurückgegeben.
* Nach dem Löschen wird der Token **sofort ungültig**, und alle Dienste, die ihn verwenden, erhalten unmittelbar `401`.
* Eine erneute Abfrage dieser `id` gibt `404` zurück.

> ⚠️ Das Löschen ist irreversibel. Wenn du vermutest, dass der Token kompromittiert wurde, kannst du **zuerst einen neuen erstellen, die Geschäftsseite umstellen und dann den alten löschen**.

***

## Nicht unterstützte Operationen

| Operation | HTTP | Beschreibung |
| - | - | - |
| `PATCH` ändern | 405 | Nach der Erstellung eines Kontotokens werden **keine Feldänderungen unterstützt**. Für Zwecke wie Umbenennen bitte löschen und neu erstellen |
| `PUT` ersetzen | 405 | Wie oben |

***

## Fehlercode-Schnellübersicht

| HTTP | `code` | Häufige Ursache |
| - | - | - |
| 401 | `not_authenticated` | Kein `Authorization`-Header mitgegeben oder Token wurde gelöscht |
| 403 | `permission_denied` | Listen-Schnittstelle ohne `?user_id=`, oder Zugriff auf Token-Details anderer Personen |
| 404 | `not_found` | `id` existiert nicht oder wurde gelöscht |
| 405 | `method_not_allowed` | `PATCH`/`PUT` an die Detail-Schnittstelle gesendet |

Einheitliches Format der Fehlerantwort:

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

Gib bei der Fehlerbehebung `trace_id` dem Kundendienst an oder füge sie in das Ticket ein, um die Protokolle schnell zu lokalisieren.

***

## Vollständige Codebeispiele

### 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. Neuen Token erstellen
created = requests.post(f"{BASE}/platform-tokens/", headers=headers, json={}).json()
print("Neuer Token:", created["token"])
print("UserID:", created["user_id"])

# 2. Liste
listing = requests.get(
    f"{BASE}/platform-tokens/",
    headers=headers,
    params={"user_id": USER_ID, "limit": 50},
).json()
print(f"Insgesamt {listing['count']} Token")

# 3. Löschen (beachte: kein Schrägstrich am Ende)
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',
}

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

// Liste
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(`Insgesamt ${listing.count} Token`)

// Löschen (kein Schrägstrich am Ende)
await fetch(`${BASE}/platform-tokens/${created.id}`, { method: 'DELETE', headers })
```

***

## Verwendung in anderen Plattform-APIs

Füge `platform-v1-...` direkt in den Header `Authorization: Bearer ...` ein, um jede Plattform-Schnittstelle aufzurufen, die eine Authentifizierung erfordert:

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

> Dies unterscheidet sich **vollständig** von den 32-stelligen hexadezimalen API-Anmeldedaten, die von den Geschäftsschnittstellen unter `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo usw.) verwendet werden. Bitte nicht verwechseln — wenn du den Kontotoken in eine Geschäftsschnittstelle schreibst, erhältst du `401`, und umgekehrt ebenso.

***

## Verwandte Schnittstellen

* [Abrufen der Liste der Serviceanträge der AceDataCloud-Plattform](https://platform.acedata.cloud/documents/platform-application-list) — Mit dem Kontotoken anzeigen, welche Dienste man selbst beantragt hat
* [Erstellen von API-Anmeldedaten für die AceDataCloud-Plattform](https://platform.acedata.cloud/documents/platform-credential-create) — Mit dem Kontotoken 32-stellige Anmeldedaten für Geschäfts-APIs ausstellen
* [Abrufen der API-Aufrufprotokolle der AceDataCloud-Plattform](https://platform.acedata.cloud/documents/platform-usage-list) — Zur Rechnungsprüfung und Fehlerbehebung
* [Abrufen der Bestellliste der AceDataCloud-Plattform](https://platform.acedata.cloud/documents/platform-order-list) — Den Aufladeverlauf einsehen


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