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

# Gestire i token dell'account della piattaforma AceDataCloud (Account Token)

> Platform API guide - Ace Data Cloud

**Il token dell'account (Account Token, precedentemente chiamato Platform Token)** è una "chiave a livello di account" che gli sviluppatori utilizzano per gestire programmaticamente le risorse della piattaforma AceDataCloud (richieste di servizio, credenziali API, ordini, registri delle chiamate, saldo, file ecc.). La sua funzione è simile al Token utente dopo il login nel frontend e, per impostazione predefinita, non ha una data di scadenza; gli utenti normali possono gestire solo i propri token, mentre i super amministratori possono gestire i token di altri account in base alle autorizzazioni.

Il token dell'account accede alle interfacce della piattaforma con le autorizzazioni correnti dell'account a cui appartiene: le autorizzazioni di base, quelle concesse direttamente e quelle dei gruppi di utenti di appartenenza vengono applicate congiuntamente; dopo l'aggiunta o la rimozione da un gruppo, la richiesta successiva verrà valutata in base alle nuove autorizzazioni. L'accesso a risorse specifiche come richieste e ordini richiede comunque una verifica di appartenenza. I token dell'account non scadono per impostazione predefinita; utilizzali solo in ambienti affidabili e conservali adeguatamente.

> ℹ️ Questa interfaccia appartiene alla **API di gestione della piattaforma AceDataCloud**, con prefisso unificato `https://platform.acedata.cloud/api/v1/`. Per l'indice completo delle interfacce, consulta l'[elenco della documentazione della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-document-list).

## Token dell'account vs credenziali API

Le due tipologie di chiavi che i principianti confondono più facilmente, chiariscile prima:

| Dimensione | **Token dell'account** (questo documento) | **Credenziali API (Credential)** |
| - | - | - |
| Utilizzo | Chiamare le interfacce di gestione `https://platform.acedata.cloud/**` | Chiamare le interfacce aziendali `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo ecc.) |
| Formato | `platform-v1-` + 64 caratteri esadecimali (76 caratteri in totale) | 32 caratteri esadecimali |
| Un account | Di solito 1–2 | 1–N per ogni richiesta di servizio |
| Punto di creazione | [Console Account Token](https://platform.acedata.cloud/console/platform-tokens) | [Creare credenziali API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) |
| Condizioni di invalidazione | Diventa immediatamente non valido dopo l'eliminazione; scade quando `expiration` non è nullo | È possibile impostare un limite di quota, una data di scadenza e associare IP di origine |

Se vuoi solo chiamare GPT-4.1, ti servono le **credenziali API**, non il token dell'account.
Se vuoi scrivere script di automazione per gestire ricariche, visualizzare fatture mensili o distribuire credenziali in blocco ai membri del team, allora usa il token dell'account.

***

## Creazione con un clic nella console (consigliato)

1. Accedi a [https://platform.acedata.cloud](https://platform.acedata.cloud).
2. Vai alla barra laterale → «Sviluppatore» → «[Account Token](https://platform.acedata.cloud/console/platform-tokens)».
3. Fai clic sul pulsante «Crea» in alto a destra per ottenere immediatamente un token `platform-v1-...`, **fai clic sul pulsante copia e salvalo nel gestore delle password**.

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

> ⚠️ Attualmente le risposte di creazione, elenco e dettagli restituiscono tutte il token in chiaro. Tratta l'intera risposta come un segreto, non scriverla nei log, nelle piattaforme di analisi o nella persistenza frontend; inoltre il client non dovrebbe dipendere dalla restituzione a lungo termine del testo in chiaro nell'elenco.

***

## Creare un token dell'account tramite API

### Panoramica dell'interfaccia

| Voce | Contenuto |
| - | - |
| Metodo | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Autenticazione | ✅ Qualsiasi token dell'account esistente oppure JWT della sessione del browser |
| Body | `application/json` (può essere passato un oggetto vuoto `{}`) |

### Istruzioni per l'autenticazione (problema dell'uovo e della gallina)

> Come si ottiene il primo token? La risposta è **tramite la console** — dopo l'accesso nel browser, la console chiama `POST /platform-tokens/` con autenticazione JWT e ti assegna il primo token.
> Successivamente puoi utilizzare qualsiasi token `platform-v1-...` esistente per crearne altri.

Formato dell'header della richiesta:

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

### Esempio di richiesta

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

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

### Descrizione dei campi

| Campo | Tipo | Descrizione |
| - | - | - |
| `id` | UUID | Chiave primaria del token, usata per l'eliminazione / la consultazione dei dettagli |
| `token` | string | Testo in chiaro del token dell'account. Formato `platform-v1-` + 64 caratteri esadecimali (76 caratteri in totale), deve essere trattato come un segreto |
| `expiration` | int \| null | Ora di scadenza (timestamp in secondi). `null` indica che non è impostata alcuna scadenza |
| `user_id` | UUID | ID dell'utente proprietario. È anche il valore del parametro `?user_id=` che deve essere passato a tutte le interfacce di elenco successive |
| `created_at` | datetime (ISO8601) | Ora di creazione |
| `updated_at` | datetime (ISO8601) | Ora di aggiornamento |
| `used_at` | datetime \| null | Ora dell'ultimo utilizzo per l'autenticazione. Se non è mai stato usato è `null`, e può essere utilizzato per individuare i "token zombie" |

***

## Ottenere l'elenco dei token dell'account

### Panoramica dell'interfaccia

| Voce | Contenuto |
| - | - |
| Metodo | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| Autenticazione | ✅ Token dell'account richiesto |

### Parametro di query obbligatorio

> ⚠️ **Devi includere `?user_id=<your_user_id>`**. Motivo: l'interfaccia di elenco esegue il controllo delle autorizzazioni **oggetto per oggetto** sui risultati paginati; se `user_id` non viene incluso, il primo oggetto che non ti appartiene verrà rifiutato, restituendo `403 permission_denied`.

Come ottenere `user_id`:

1. Apri nel browser [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile), nella parte superiore della pagina viene visualizzato l'UUID completo.
2. Oppure inserisci direttamente il campo `user_id` nel valore restituito da `POST /platform-tokens/`.

### Parametri di query

| Parametro | Obbligatorio | Tipo | Descrizione |
| - | - | - | - |
| `user_id` | ✅ | UUID | ID utente dell'account corrente |
| `limit` | ❌ | int | Numero di elementi per pagina, predefinito 10, massimo 100 |
| `offset` | ❌ | int | Offset |
| `ordering` | ❌ | string | Campo di ordinamento, predefinito `-created_at` |

### Esempio di richiesta

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

### Risposta (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 risposta paginata di questa interfaccia utilizza `count` + `items`. Altre interfacce della piattaforma potrebbero utilizzare strutture diverse; fare riferimento alla documentazione corrispondente e alla risposta effettiva.

***

## Ottieni i dettagli del token dell'account

| Voce | Contenuto |
| - | - |
| Metodo | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**senza barra finale**） |
| Autorizzazione | ✅ Accessibile solo al creatore del token o al super amministratore |

```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 struttura restituita è coerente con l'elemento della lista, `HTTP 200`.

***

## Elimina il token dell'account

| Voce | Contenuto |
| - | - |
| Metodo | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**senza barra finale**） |
| Autorizzazione | ✅ Può essere eliminato solo dal creatore del token o dal super amministratore |

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

* In caso di successo restituisce `HTTP 204 No Content`, senza corpo della risposta.
* Dopo l'eliminazione, il token **diventa immediatamente non valido** e tutti i servizi che lo stanno utilizzando riceveranno subito `401`.
* Una nuova query di questo `id` restituirà `404`.

> ⚠️ L'eliminazione è irreversibile. Se sospetti che il token sia stato divulgato, puoi **prima crearne uno nuovo, cambiare lato business, poi eliminare quello vecchio**.

***

## Operazioni non supportate

| Operazione | HTTP | Descrizione |
| - | - | - |
| Modifica `PATCH` | 405 | Dopo la creazione, il token dell'account **non supporta la modifica di alcun campo**. Per scopi quali la ridenominazione, eliminare e ricreare |
| Sostituzione `PUT` | 405 | Come sopra |

***

## Riferimento rapido dei codici di errore

| HTTP | `code` | Causa comune |
| - | - | - |
| 401 | `not_authenticated` | Header `Authorization` assente, o token eliminato |
| 403 | `permission_denied` | L'interfaccia della lista non include `?user_id=`, o si accede ai dettagli del token di un'altra persona |
| 404 | `not_found` | L'`id` non esiste o è stato eliminato |
| 405 | `method_not_allowed` | È stato inviato `PATCH`/`PUT` all'interfaccia dei dettagli |

Formato unificato della risposta di errore:

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

Durante la risoluzione dei problemi, fornisci `trace_id` al servizio clienti o inseriscilo nel ticket per individuare rapidamente i log.

***

## Esempio di codice completo

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

***

## Utilizzo in altre API della piattaforma

Inserisci direttamente `platform-v1-...` nell'header `Authorization: Bearer ...` per chiamare qualsiasi interfaccia della piattaforma che richieda l'autorizzazione:

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

> È **completamente diverso** dalle credenziali API esadecimali a 32 caratteri utilizzate dalle interfacce business `https://api.acedata.cloud/**` (OpenAI, Midjourney, Suno, Veo ecc.). Non confonderli: inserire il token dell'account nell'interfaccia business restituirà `401`, e viceversa.

***

## Interfacce correlate

* [Ottieni l'elenco delle richieste di servizi della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-application-list) — usa il token dell'account per vedere quali servizi hai richiesto
* [Crea le credenziali API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-credential-create) — usa il token dell'account per emettere credenziali a 32 caratteri per le API aziendali
* [Ottieni i registri delle chiamate API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-usage-list) — per verificare i conti e risolvere gli errori
* [Ottieni l'elenco degli ordini della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-order-list) — per controllare la cronologia delle ricariche


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