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

# Керування токенами облікового запису платформи AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**Токен облікового запису (Account Token, раніше Platform Token)** — це «ключ рівня облікового запису», за допомогою якого розробники програмним способом керують ресурсами платформи AceDataCloud (заявки на послуги, API-облікові дані, замовлення, записи викликів, баланс, файли тощо). Його роль подібна до Token користувача після входу у фронтенд, за замовчуванням він не має терміну дії; звичайні користувачі можуть керувати лише власними токенами, а суперадміністратори можуть керувати токенами інших облікових записів відповідно до дозволів.

Токен облікового запису отримує доступ до інтерфейсів платформи з поточними дозволами облікового запису: базові дозволи, безпосередньо надані дозволи та дозволи груп користувачів, до яких він належить, об’єднуються й набувають чинності; після додавання до групи або видалення з неї наступний запит оцінюватиметься за новими дозволами. Для доступу до конкретних ресурсів, таких як заявки та замовлення, все одно потрібна перевірка належності. Токени облікового запису за замовчуванням не мають терміну дії, використовуйте їх лише в довіреному середовищі та належним чином зберігайте.

> ℹ️ Цей інтерфейс належить до **API керування платформою AceDataCloud**, з єдиним префіксом `https://platform.acedata.cloud/api/v1/`. Повний індекс інтерфейсів див. у [Отримання списку документації платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Токен облікового запису vs API-облікові дані

Два типи ключів, які новачки найчастіше плутають, спершу чітко розберіться:

| Вимір | **Токен облікового запису** (цей документ) | **API-облікові дані (Credential)** |
| - | - | - |
| Призначення | Виклик інтерфейсів керування `https://platform.acedata.cloud/**` | Виклик бізнес-інтерфейсів `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo тощо) |
| Формат | `platform-v1-` + 64-значне шістнадцяткове число (усього 76 символів) | 32-значне шістнадцяткове число |
| Один обліковий запис | Зазвичай 1–2 токени | 1–N токенів для кожної заявки на послугу |
| Точка створення | [Консоль Account Token](https://platform.acedata.cloud/console/platform-tokens) | [Створення API-облікових даних платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| Умови втрати чинності | Відразу втрачає чинність після видалення; якщо `expiration` не порожнє — втрачає чинність після закінчення терміну | Можна встановити ліміт квоти, термін дії та прив’язати вихідну IP-адресу |

Якщо ви лише хочете викликати GPT-4.1, вам потрібні **API-облікові дані**, а не токен облікового запису.
Якщо ви хочете написати автоматизований скрипт для керування поповненнями, перегляду щомісячних рахунків або масового надсилання облікових даних членам команди, тоді використовуйте токен облікового запису.

***

## Створення в консолі одним кліком (рекомендовано)

1. Увійдіть до [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. Перейдіть у бічному меню → «Розробник» → «[Account Token](https://platform.acedata.cloud/console/platform-tokens)».
3. Натисніть кнопку «Створити» у верхньому правому куті, і одразу отримаєте токен `platform-v1-...`; **натисніть кнопку копіювання та збережіть його в менеджері паролів**.

![Консоль Account Token](https://cdn.acedata.cloud/6g86oz.png)

> ⚠️ Поточні відповіді на створення, список і деталі повертають токен у відкритому вигляді. Обробляйте всю відповідь як секрет: не записуйте її в журнали, аналітичні платформи або постійне сховище фронтенду; клієнт також не повинен покладатися на те, що список тривалий час повертатиме токен у відкритому вигляді.

***

## Створення токена облікового запису через API

### Огляд інтерфейсу

| Пункт | Вміст |
| - | - |
| Метод | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Авторизація | ✅ Будь-який наявний токен облікового запису або JWT стану входу в браузері |
| Body | `application/json` (можна передати порожній об’єкт `{}`) |

### Пояснення авторизації (проблема курки та яйця)

> Як отримати перший токен? Відповідь — **через консоль**: після входу в браузері консоль використовує JWT-авторизацію для виклику `POST /platform-tokens/` і видає вам перший токен.
> Після цього ви можете використовувати будь-який наявний токен `platform-v1-...`, щоб створити більше токенів.

Формат заголовків запиту:

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

### Приклад запиту

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

### Відповідь (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
}
```

### Опис полів

| Поле | Тип | Опис |
| - | - | - |
| `id` | UUID | Первинний ключ токена, використовується для видалення / запиту деталей |
| `token` | string | Відкритий текст токена облікового запису. Формат: `platform-v1-` + 64-значне шістнадцяткове число (усього 76 символів), його необхідно обробляти як секрет |
| `expiration` | int \| null | Час закінчення дії (мітка часу в секундах). `null` означає, що час закінчення дії не встановлено |
| `user_id` | UUID | ID користувача-власника. Це також значення параметра `?user_id=`, яке обов’язково потрібно передавати в усіх наступних інтерфейсах списків |
| `created_at` | datetime (ISO8601) | Час створення |
| `updated_at` | datetime (ISO8601) | Час оновлення |
| `used_at` | datetime \| null | Час останнього використання для авторизації. Якщо ніколи не використовувався — `null`; можна застосовувати для виявлення «токенів-зомбі» |

***

## Отримання списку токенів облікового запису

### Огляд інтерфейсу

| Пункт | Вміст |
| - | - |
| Метод | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Авторизація | ✅ Потрібен токен облікового запису |

### Обов’язкові параметри запиту

> ⚠️ **Обов’язково додайте `?user_id=<your_user_id>`**. Причина: інтерфейс списку виконує перевірку дозволів **для кожного об’єкта** в результатах пагінації; якщо не передати `user_id`, перший об’єкт, який вам не належить, буде відхилено, і повернеться `403 permission_denied`.

Як отримати `user_id`:

1. Відкрийте в браузері [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile), у верхній частині сторінки буде показано повний UUID.
2. Або безпосередньо підставте назад поле `user_id` зі значення, поверненого `POST /platform-tokens/`.

### Параметри запиту

| Параметр | Обов'язковий | Тип | Опис |
| - | - | - | - |
| `user_id` | ✅ | UUID | ID користувача поточного облікового запису |
| `limit` | ❌ | int | Кількість записів на сторінку, за замовчуванням 10, максимум 100 |
| `offset` | ❌ | int | Зсув |
| `ordering` | ❌ | string | Поле сортування, за замовчуванням `-created_at` |

### Приклад запиту

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

### Відповідь（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
    }
  ]
}
```

> Пагінована відповідь цього інтерфейсу використовує `count` + `items`. Інші інтерфейси платформи можуть використовувати іншу структуру, будь ласка, орієнтуйтеся на відповідну документацію та фактичну відповідь.

***

## Отримати деталі токена облікового запису

| Пункт | Вміст |
| - | - |
| Метод | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**без косої риски в кінці**） |
| Авторизація | ✅ Доступ мають лише творець токена або суперадміністратор |

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

Структура повернення відповідає елементу списку, `HTTP 200`.

***

## Видалити токен облікового запису

| Пункт | Вміст |
| - | - |
| Метод | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**без косої риски в кінці**） |
| Авторизація | ✅ Видалити можуть лише творець токена або суперадміністратор |

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

* У разі успіху повертається `HTTP 204 No Content`, без тіла відповіді.
* Після видалення цей токен **негайно стає недійсним**, усі служби, що використовують його, одразу отримають `401`.
* Повторний запит цього `id` поверне `404`.

> ⚠️ Видалення незворотне. Якщо ви підозрюєте витік токена, можна **спочатку створити новий, переключити бізнес-сторону, а потім видалити старий**.

***

## Непідтримувані операції

| Операція | HTTP | Опис |
| - | - | - |
| Зміна `PATCH` | 405 | Після створення токена облікового запису **зміна будь-яких полів не підтримується**. Для таких цілей, як перейменування, видаліть і створіть заново |
| Заміна `PUT` | 405 | Те саме |

***

## Швидкий довідник кодів помилок

| HTTP | `code` | Поширена причина |
| - | - | - |
| 401 | `not_authenticated` | Не передано заголовок `Authorization` або токен було видалено |
| 403 | `permission_denied` | В інтерфейсі списку не передано `?user_id=` або здійснюється доступ до деталей чужого токена |
| 404 | `not_found` | `id` не існує або був видалений |
| 405 | `method_not_allowed` | До інтерфейсу деталей надіслано `PATCH`/`PUT` |

Уніфікований формат відповіді про помилку:

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

Під час діагностики надайте `trace_id` службі підтримки або вставте його в тікет, це дасть змогу швидко знайти журнали.

***

## Повний приклад коду

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

***

## Використання в інших API платформи

Безпосередньо помістіть `platform-v1-...` у заголовок `Authorization: Bearer ...`, щоб викликати будь-який інтерфейс платформи, який потребує авторизації:

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

> Він **повністю відрізняється** від 32-значних шістнадцяткових облікових даних API, що використовуються бізнес-інтерфейсами `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo тощо). Не змішуйте їх — якщо записати токен облікового запису в бізнес-інтерфейс, отримаєте `401`, і навпаки.

***

## Пов'язані інтерфейси

* [Отримати список заявок на послуги платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — переглянути за допомогою токена облікового запису, на які послуги ви подали заявку
* [Створити облікові дані API платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — видати за допомогою токена облікового запису 32-символьні облікові дані для бізнес-API
* [Отримати записи викликів API платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — для перевірки рахунків і усунення помилок
* [Отримати список замовлень платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — переглянути історію поповнень


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