> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API de gestión

> Administra el saldo de la organización, las claves API y el uso y facturación por clave mediante un token de gestión.

## Resumen

La API de gestión te permite consultar los totales de saldo de la organización, administrar las claves API de la organización y consultar uso y facturación por clave sin usar una clave estándar de inferencia.

Emite el token de gestión desde la página **Settings** de tu Dashboard:

```bash theme={null}
Authorization: Bearer mt-your-management-token
```

<Warning>
  Los tokens de gestión son distintos de las claves API de inferencia. Usa `mt-...` para `/v1/management/*` y `sk-...` para endpoints de inferencia como `/v1/responses`.
</Warning>

## Endpoints disponibles

| Endpoint                                  | Method | Descripción                                                               |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------- |
| `/v1/management/balance`                  | GET    | Devuelve los totales actuales de saldo de la organización                 |
| `/v1/management/api-keys`                 | GET    | Lista las claves API administradas por usuarios de la organización actual |
| `/v1/management/api-keys`                 | POST   | Crea una nueva clave API de usuario                                       |
| `/v1/management/api-keys/{keyId}`         | PATCH  | Actualiza nombre, límite de uso, modelos permitidos, caducidad o estado   |
| `/v1/management/api-keys/{keyId}/usage`   | GET    | Devuelve el detalle paginado de uso de una clave específica               |
| `/v1/management/api-keys/{keyId}/billing` | GET    | Devuelve el desglose agregado de facturación de una clave específica      |

## Contrato de filtros de uso

`GET /v1/management/api-keys/{keyId}/usage` admite los siguientes parámetros de consulta:

| Parámetro       | Tipo    | Valor predeterminado / límites                | Notas                                                                                              |
| --------------- | ------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | predeterminado `1`, mínimo `1`                | Número de página basado en 1                                                                       |
| `limit`         | integer | predeterminado `50`, mínimo `1`, máximo `100` | Tamaño de página                                                                                   |
| `model`         | string  | longitud máxima `100`                         | Nombre del modelo solicitado                                                                       |
| `modelVendor`   | string  | longitud máxima `100`                         | Proveedor público del modelo                                                                       |
| `scene`         | enum    | -                                             | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                                             | `platform` o `byok`                                                                                |
| `startDate`     | string  | -                                             | Límite inferior inclusivo; acepta RFC3339 con zona horaria o `YYYY-MM-DD`                          |
| `endDate`       | string  | -                                             | Límite superior inclusivo; acepta RFC3339 con zona horaria o `YYYY-MM-DD`                          |

Si `startDate` y `endDate` están presentes, `startDate` debe ser anterior o igual a `endDate`.

## Contrato del cuerpo de la clave API

### POST /v1/management/api-keys

| Campo           | Tipo           | Valor predeterminado / límites                           | Notas                                                                                                                                                     |
| --------------- | -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | string         | requerido, predeterminado `Default Key`, longitud `1-50` | Nombre visible, recortado en el servidor                                                                                                                  |
| `limitAmount`   | number \| null | mínimo `0`, máximo de entrada `1000000`                  | `null` o omitido = ilimitado, `0` = cuota cero. Los valores positivos se normalizan a un límite almacenado que no puede superar `100000` USD equivalente. |
| `limitCurrency` | enum           | default `USD`                                            | Solo USD. Enviar `CNY` devuelve `400 currency_retired`.                                                                                                   |
| `models`        | string\[]      | predeterminado `[]`                                      | Lista opcional de modelos lógicos permitidos                                                                                                              |
| `expiresAt`     | string \| null | datetime RFC3339                                         | `null` significa sin caducidad                                                                                                                            |

### PATCH /v1/management/api-keys/{keyId}

| Campo           | Tipo           | Valor predeterminado / límites          | Notas                                                                                                                                           |
| --------------- | -------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`        | enum           | -                                       | `active`, `inactive`, `revoked`                                                                                                                 |
| `name`          | string         | longitud `1-50`                         | Nombre visible actualizado                                                                                                                      |
| `limitAmount`   | number \| null | mínimo `0`, máximo de entrada `1000000` | `null` = ilimitado, `0` = cuota cero. Los valores positivos se normalizan a un límite almacenado que no puede superar `100000` USD equivalente. |
| `limitCurrency` | enum           | default `USD`                           | Solo USD. Enviar `CNY` devuelve `400 currency_retired`.                                                                                         |
| `models`        | string\[]      | -                                       | Lista actualizada de modelos lógicos permitidos                                                                                                 |
| `expiresAt`     | string \| null | datetime RFC3339                        | `null` elimina la caducidad                                                                                                                     |

Debe proporcionarse al menos un campo de PATCH.

## Contrato monetario

## Semántica de reporting

* `model` se refiere al modelo público solicitado por el llamador.
* `modelVendor` se refiere al proveedor público del modelo, no a la ruta física oculta.
* `scene` es la escena pública de la solicitud derivada del endpoint o del tipo de tarea.
* `accessChannel=platform` significa que la solicitud se facturó mediante el canal de plataforma de TokenLab.
* `accessChannel=byok` significa que la solicitud usó su propia clave del proveedor upstream.

Las respuestas exponen solo campos públicos de facturación y reporting. Los detalles internos de enrutamiento y los metadatos físicos del proveedor permanecen ocultos.

* Los elementos de `/usage` pueden incluir `billing_transaction_id` una vez que la solicitud subyacente haya alcanzado el estado de liquidación. Usa `request_id` + `billing_transaction_id` para conciliación a nivel de solicitud.

## Nota sobre paginación de billing

`/usage` está paginado. `/billing` es actualmente un endpoint agregado y no devuelve metadatos de paginación estilo `page` / `limit`. Si necesitas registros de línea, usa `/usage`.

## Ejemplo rápido

Empieza consultando el saldo de la organización con el token de gestión actual.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

Luego lista las API keys disponibles para ese mismo token de gestión.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/management/api-keys" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "key_abc123def456",
        "name": "Backend Worker",
        "key_prefix": "sk-abc123...",
        "status": "active",
        "limit_amount": 500.0,
        "limit_amount_decimal": "500",
        "used_amount": 148.25,
        "used_amount_decimal": "148.25",
        "models": ["gpt-4o-mini", "claude-3-7-sonnet"],
        "expires_at": "2026-04-30T00:00:00.000Z",
        "last_used_at": "2026-03-27T08:12:45.000Z",
        "created_at": "2026-03-01T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>

## Próximos pasos

* [Listar API Keys](/api-reference/management/list-api-keys)
* [Crear API Key](/api-reference/management/create-api-key)
* [Actualizar API Key](/api-reference/management/update-api-key)
* [Obtener uso de API Key](/api-reference/management/get-api-key-usage)
* [Obtener facturación de API Key](/api-reference/management/get-api-key-billing)