> ## 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과 유사하며, 기본적으로 만료 시간이 없습니다. 일반 사용자는 자신의 토큰만 관리할 수 있고, 슈퍼 관리자는 권한에 따라 다른 계정의 토큰을 관리할 수 있습니다.

계정 토큰은 소속 계정의 현재 권한으로 플랫폼 인터페이스에 접근합니다. 기본 권한, 직접 부여된 권한 및 소속 사용자 그룹 권한이 병합되어 적용되며, 그룹 가입 또는 탈퇴 후 다음 요청부터 새 권한에 따라 판단됩니다. 구체적인 신청, 주문 등의 리소스 접근은 여전히 소유권 검증을 통과해야 합니다. 계정 토큰은 기본적으로 만료되지 않으므로, 신뢰할 수 있는 환경에서만 사용하고 안전하게 보관하세요.

> ℹ️ 이 인터페이스는 **AceDataCloud 플랫폼 관리 API**에 속하며, 공통 접두사는 `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자리 16진수(총 76자) | 32자리 16진수 |
| 하나의 계정 | 일반적으로 1–2개 | 서비스 신청당 1–N개 |
| 생성 진입점 | [Account Token 콘솔](https://platform.acedata.cloud/console/platform-tokens) | [AceDataCloud 플랫폼 API 자격 증명 생성](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자리 16진수(총 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. 또는 `POST /platform-tokens/` 반환값의 `user_id` 필드를 직접 다시 입력합니다.

### 쿼리 매개변수

| 매개변수 | 필수 | 유형 | 설명 |
| - | - | - | - |
| `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}"
```

> `https://api.acedata.cloud/**` 비즈니스 인터페이스(OpenAI, Midjourney, Suno, Veo 등)에서 사용하는 32자리 16진수 API 자격 증명과는 **완전히 다릅니다**. 혼용하지 마십시오——계정 토큰을 비즈니스 인터페이스에 입력하면 `401`을 받고, 그 반대도 마찬가지입니다.

***

## 관련 인터페이스

* [AceDataCloud 플랫폼 서비스 신청 목록 가져오기](https://platform.acedata.cloud/documents/platform-application-list) — 계정 토큰으로 자신이 신청한 서비스를 확인합니다
* [AceDataCloud 플랫폼 API 자격 증명 생성하기](https://platform.acedata.cloud/documents/platform-credential-create) — 계정 토큰으로 비즈니스 API용 32자리 자격 증명을 발급합니다
* [AceDataCloud 플랫폼 API 호출 기록 가져오기](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.