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

# Zarządzanie tokenami konta platformy AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**Token konta (Account Token, wcześniej nazywany Platform Token)** jest „kluczem na poziomie konta”, za pomocą którego deweloperzy programowo zarządzają zasobami platformy AceDataCloud (wnioskami o usługi, poświadczeniami API, zamówieniami, rejestrami wywołań, saldem, plikami itd.). Jego działanie jest podobne do Tokena użytkownika po zalogowaniu się w interfejsie frontendowym i domyślnie nie ma terminu ważności; zwykli użytkownicy mogą zarządzać wyłącznie własnymi tokenami, a superadministratorzy mogą zarządzać tokenami innych kont zgodnie z uprawnieniami.

Token konta uzyskuje dostęp do interfejsów platformy z bieżącymi uprawnieniami należącego do niego konta: uprawnienia podstawowe, uprawnienia nadane bezpośrednio oraz uprawnienia grup użytkowników są łączone i obowiązują razem; po dołączeniu do grupy lub usunięciu z niej kolejne żądanie zostanie ocenione według nowych uprawnień. Dostęp do konkretnych zasobów, takich jak wnioski i zamówienia, nadal wymaga weryfikacji przynależności. Token konta domyślnie nie wygasa, dlatego używaj go wyłącznie w zaufanym środowisku i przechowuj go bezpiecznie.

> ℹ️ Ten interfejs należy do **API zarządzania platformą AceDataCloud**, ze wspólnym prefiksem `https://platform.acedata.cloud/api/v1/`. Pełny indeks interfejsów znajduje się w [Pobierz listę dokumentacji platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Token konta vs poświadczenia API

Dwa rodzaje kluczy, które początkujący najczęściej mylą — najpierw wyraźnie je rozróżnij:

| Wymiar | **Token konta** (ten dokument) | **Poświadczenia API (Credential)** |
| - | - | - |
| Zastosowanie | Wywoływanie interfejsów administracyjnych `https://platform.acedata.cloud/**` | Wywoływanie interfejsów biznesowych `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo itd.) |
| Format | `platform-v1-` + 64 znaki szesnastkowe (łącznie 76 znaków) | 32 znaki szesnastkowe |
| Jedno konto | Zwykle 1–2 sztuki | 1–N sztuk dla każdego wniosku o usługę |
| Punkt tworzenia | [Konsola Account Token](https://platform.acedata.cloud/console/platform-tokens) | [Utwórz poświadczenia API platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| Warunki unieważnienia | Wygasa natychmiast po usunięciu; wygasa po terminie, gdy `expiration` nie jest puste | Można ustawić limit kwoty, czas wygaśnięcia i powiązać źródłowy adres IP |

Jeśli chcesz tylko wywołać GPT-4.1, potrzebujesz **poświadczeń API**, a nie tokena konta.
Jeśli chcesz napisać skrypt automatyzujący zarządzanie doładowaniami, przeglądanie miesięcznych rachunków lub masowe wydawanie poświadczeń członkom zespołu, wtedy użyj tokena konta.

***

## Utwórz jednym kliknięciem w konsoli (zalecane)

1. Zaloguj się do [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. Przejdź do paska bocznego → „Deweloper” → „[Account Token](https://platform.acedata.cloud/console/platform-tokens)”.
3. Kliknij przycisk „Utwórz” w prawym górnym rogu, aby natychmiast otrzymać token `platform-v1-...`; **kliknij przycisk kopiowania i zapisz go w menedżerze haseł**.

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

> ⚠️ Obecnie odpowiedzi dotyczące tworzenia, listy i szczegółów zwracają token w postaci jawnego tekstu. Traktuj całą odpowiedź jako sekret — nie zapisuj jej w logach, platformach analitycznych ani trwałej pamięci frontendu; klient nie powinien również polegać na tym, że lista długoterminowo będzie zwracać tekst jawny.

***

## Tworzenie tokena konta za pomocą API

### Przegląd interfejsu

| Element | Treść |
| - | - |
| Metoda | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Uwierzytelnianie | ✅ Dowolny istniejący token konta lub JWT sesji logowania w przeglądarce |
| Body | `application/json` (można przekazać pusty obiekt `{}`) |

### Wyjaśnienie uwierzytelniania (problem jajka i kury)

> Skąd wziąć pierwszy token? Odpowiedź brzmi: **przez konsolę** — po zalogowaniu w przeglądarce konsola wywołuje `POST /platform-tokens/` z uwierzytelnianiem JWT i wydaje Ci pierwszy token.
> Następnie możesz użyć dowolnego istniejącego tokena `platform-v1-...`, aby utworzyć kolejne.

Format nagłówków żądania:

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

### Przykład żądania

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

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

### Opis pól

| Pole | Typ | Opis |
| - | - | - |
| `id` | UUID | Klucz główny tokena, używany przy usuwaniu / pobieraniu szczegółów |
| `token` | string | Jawny tekst tokena konta. Format: `platform-v1-` + 64 znaki szesnastkowe (łącznie 76 znaków); należy traktować go jako sekret |
| `expiration` | int \| null | Czas wygaśnięcia (znacznik czasu w sekundach). `null` oznacza, że czas wygaśnięcia nie został ustawiony |
| `user_id` | UUID | ID należącego użytkownika. Jest to również wartość parametru `?user_id=`, który należy przekazać we wszystkich kolejnych interfejsach list |
| `created_at` | datetime (ISO8601) | Czas utworzenia |
| `updated_at` | datetime (ISO8601) | Czas aktualizacji |
| `used_at` | datetime \| null | Czas ostatniego użycia do uwierzytelniania. Jeśli nigdy nie został użyty, ma wartość `null`; można go użyć do wykrywania „tokenów zombie” |

***

## Pobieranie listy tokenów konta

### Przegląd interfejsu

| Element | Treść |
| - | - |
| Metoda | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Uwierzytelnianie | ✅ Wymaga tokena konta |

### Wymagane parametry zapytania

> ⚠️ **Musisz przekazać `?user_id=<your_user_id>`**. Powód: interfejs listy wykonuje kontrolę uprawnień **dla każdego obiektu** w wynikach paginacji; gdy nie przekażesz `user_id`, pierwszy obiekt, który do Ciebie nie należy, zostanie odrzucony i zwróci `403 permission_denied`.

Jak uzyskać `user_id`:

1. Otwórz w przeglądarce [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile); pełny UUID jest wyświetlany u góry strony.
2. Możesz też bezpośrednio wpisać ponownie wartość pola `user_id` z odpowiedzi `POST /platform-tokens/`.

### Parametry zapytania

| Parametr | Wymagane | Typ | Opis |
| - | - | - | - |
| `user_id` | ✅ | UUID | ID użytkownika bieżącego konta |
| `limit` | ❌ | int | Liczba pozycji na stronę, domyślnie 10, maksymalnie 100 |
| `offset` | ❌ | int | Przesunięcie |
| `ordering` | ❌ | string | Pole sortowania, domyślnie `-created_at` |

### Przykład żądania

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

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

> Odpowiedź stronicowana tego interfejsu używa `count` + `items`. Inne interfejsy platformy mogą używać innej struktury; należy kierować się odpowiednią dokumentacją i rzeczywistą odpowiedzią.

***

## Pobieranie szczegółów tokena konta

| Pozycja | Treść |
| - | - |
| Metoda | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**bez ukośnika na końcu**） |
| Autoryzacja | ✅ Dostępny tylko dla twórcy tokena lub superadministratora |

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

Struktura zwracana jest zgodna z elementem listy, `HTTP 200`.

***

## Usuwanie tokena konta

| Pozycja | Treść |
| - | - |
| Metoda | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**bez ukośnika na końcu**） |
| Autoryzacja | ✅ Usunąć może tylko twórca tokena lub superadministrator |

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

* Przy powodzeniu zwracane jest `HTTP 204 No Content`, bez treści odpowiedzi.
* Po usunięciu token **natychmiast traci ważność**, a wszystkie usługi, które go używają, od razu otrzymają `401`.
* Ponowne zapytanie o ten `id` zwróci `404`.

> ⚠️ Usunięcie jest nieodwracalne. Jeśli podejrzewasz wyciek tokena, możesz **najpierw utworzyć nowy, przełączyć stronę biznesową, a następnie usunąć stary**.

***

## Nieobsługiwane operacje

| Operacja | HTTP | Opis |
| - | - | - |
| Modyfikacja `PATCH` | 405 | Po utworzeniu token konta **nie obsługuje modyfikacji żadnych pól**. W przypadku potrzeby zmiany nazwy itp. należy usunąć go i utworzyć ponownie |
| Zastąpienie `PUT` | 405 | Jak wyżej |

***

## Szybki przegląd kodów błędów

| HTTP | `code` | Częsta przyczyna |
| - | - | - |
| 401 | `not_authenticated` | Brak nagłówka `Authorization` lub token został usunięty |
| 403 | `permission_denied` | Interfejs listy nie zawiera `?user_id=` lub następuje dostęp do szczegółów tokena innej osoby |
| 404 | `not_found` | `id` nie istnieje lub został usunięty |
| 405 | `method_not_allowed` | Wysłano `PATCH`/`PUT` do interfejsu szczegółów |

Ujednolicony format odpowiedzi błędu:

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

Podczas diagnozowania przekaż `trace_id` obsłudze klienta lub umieść go w zgłoszeniu, aby szybko zlokalizować logi.

***

## Pełne przykłady kodu

### 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 })
```

***

## Używanie w innych interfejsach API platformy

Umieść `platform-v1-...` bezpośrednio w nagłówku `Authorization: Bearer ...`, aby wywołać dowolny interfejs platformy wymagający autoryzacji:

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

> Jest on **całkowicie inny** niż 32-znakowe szesnastkowe poświadczenie API używane przez interfejsy biznesowe `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo itd.). Nie należy ich mieszać — wpisanie tokena konta do interfejsu biznesowego spowoduje `401` i odwrotnie.

***

## Powiązane interfejsy

* [Pobieranie listy wniosków o usługi platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — użyj tokenu konta, aby sprawdzić, o jakie usługi samodzielnie wnioskowałeś
* [Tworzenie poświadczeń API platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — użyj tokenu konta, aby wystawić 32-znakowe poświadczenia do użycia przez biznesowe API
* [Pobieranie historii wywołań API platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — sprawdzanie rozliczeń i usuwanie błędów
* [Pobieranie listy zamówień platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — sprawdzanie historii doładowań


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