La API del Manager es la misma que usa el propio panel: todo lo que puedes hacer desde la web (crear y gestionar VPS, encenderlos y apagarlos, firewall, IPs, backups, facturación, tickets...) está disponible como llamadas HTTP con respuestas JSON, listo para integrarlo en tu propio software.

:::info
**URL base**: `https://manager.ginernet.com/api`. Todas las peticiones y respuestas usan JSON (`Content-Type: application/json`).
:::

## La referencia interactiva

Con tu sesión iniciada en el Manager, abre [https://manager.ginernet.com/api](https://manager.ginernet.com/api): es la referencia completa de la API para clientes (Swagger UI), con más de 300 operaciones organizadas por categorías, cada una con sus parámetros, cuerpo de petición y respuestas. Desde ahí puedes incluso probar llamadas reales con tu propia sesión.

La especificación OpenAPI en formato máquina está en `https://manager.ginernet.com/api/doc.json`: puedes importarla en Postman o generar un cliente para tu lenguaje con herramientas como *openapi-generator*. Es accesible con sesión o con un token de API.

## Autenticación: tokens de API (recomendado)

La forma recomendada de autenticar tu integración es con un **token de API**: una credencial que va atada a tu cuenta de cliente y que se envía en cada petición con la cabecera `Authorization`. Sin usuario, sin contraseña, sin 2FA y sin cookies.

Los tokens se crean en el Manager, en **Acceso API** (menú lateral). Al crearlo eliges:

- **IPs permitidas** (recomendado): una lista de IPs o rangos CIDR desde los que el token puede usarse. Cualquier petición desde otra IP se rechaza, así que un token filtrado no sirve de nada fuera de tus servidores.
- **Solo lectura**: el token solo puede consultar información; ninguna escritura.
- **Operaciones sensibles**: por defecto un token **no** puede ejecutar operaciones marcadas como sensibles (revelar credenciales, gestionar accesos, cambios de titularidad...). Actívalo solo si tu integración lo necesita.
- **Caducidad** opcional.

El token se muestra **una sola vez** al crearlo (empieza por `gcpr_`); guárdalo en un gestor de secretos. Usarlo es una cabecera:

```bash
curl -H 'Authorization: Bearer gcpr_TU_TOKEN' https://manager.ginernet.com/api/vps
```

Con token no hay sesión ni contexto que fijar: el token ya sabe a qué cliente pertenece, y las escrituras **no** necesitan la cabecera `Origin` (eso es una protección para las sesiones con cookie).

:::info
Qué **no** puede hacer un token, por diseño: gestionar la cuenta personal del usuario (login, 2FA, perfil), gestionar otros tokens o las claves de agentes IA, ni usar los agentes de IA del panel. Solo la **cuenta principal** del cliente puede crear y revocar tokens, y cada creación pide confirmación con passkey si la tienes configurada.
:::

Si una llamada devuelve `401` con token, el token es inválido, ha caducado, ha sido revocado o llega desde una IP no permitida (el mensaje lo indica). Un `403` significa que la operación existe pero ese token no puede ejecutarla (es de solo lectura, o la operación es sensible y el token no lo permite).

## Alternativa: sesión con cookie

La API también acepta la misma sesión que usa el panel, pensada para cuando pruebas llamadas desde la referencia interactiva. Resumen del flujo, si la necesitas:

1. `POST /api/auth/login` con `{"identifier": "...", "password": "..."}`. Guarda las cookies de la respuesta y reenvíalas en cada llamada. Si el usuario tiene passkey o TOTP, el login exige el segundo factor (`step` distinto de `complete`), que un script no puede completar en el caso de la passkey.
2. Toda escritura (`POST`, `PUT`, `PATCH`, `DELETE`) debe llevar la cabecera `Origin: https://manager.ginernet.com` (protección CSRF).
3. Fija el **cliente activo** antes de operar servicios: `GET /api/me` devuelve `accessibleClients` y `POST /api/auth/context` con `{"clientId": <id>}` lo selecciona.
4. La sesión caduca a los 60 minutos de inactividad: ante un `401`, vuelve a hacer login.

Para integraciones de verdad, usa tokens: no dependen de contraseñas, no caducan por inactividad y puedes limitarlos por IP y permisos.

## Cómo está organizada la API

Las operaciones se agrupan por categorías. Las principales:

| Categoría | Rutas típicas | Qué cubre |
|---|---|---|
| VDC | `/api/vdcs/*` | Los Virtual Data Centers donde viven tus VPS |
| VPS | `/api/vps/*`, alta en `/api/vdcs/{id}/vps` | Ciclo de vida completo: alta, recursos, energía, reinstalación, backups, contraseñas, métricas |
| VPS Firewall | `/api/vps/{id}/firewall/*` | Firewall de plataforma del VPS: modo, reglas, plantillas |
| VPS Network | `/api/vps/{id}/network/*` | IP principal e IPs adicionales |
| IPv4 / IPv6 / rDNS | `/api/ipv4/*`, `/api/ipv6/*` | Subredes contratadas, direcciones y registros PTR |
| SSH Keys | `/api/ssh-keys/*` | Librería de claves SSH del cliente |
| Tasks | `/api/tasks/*` | Seguimiento de operaciones asíncronas |
| Billing | `/api/billing/*` | Saldo, movimientos, recargas, facturas |
| Support Tickets | `/api/support-tickets/*` | Tickets de soporte y adjuntos |
| API Tokens | `/api/client/api-tokens` | Gestión de tokens (solo con sesión, nunca con token) |

La lista completa, operación a operación, está en la referencia interactiva.

## Operaciones asíncronas: las tasks

Todo lo que no es inmediato (crear un VPS, redimensionar, reinstalar, hacer un backup...) devuelve una **task**. La respuesta incluye su `id`; consulta el progreso con `GET /api/tasks/{id}` hasta que `status` sea `succeeded` o `failed`. Sondea cada 10-20 segundos, no en bucle cerrado.

## Errores y límites

- Los errores `4xx` devuelven `{"message": "..."}`, a veces con `code` y `details`. Un `404` también significa que el recurso no pertenece a tu cliente.
- Los errores `5xx` devuelven un mensaje genérico con un `errorId`: guárdalo e inclúyelo si abres un ticket de soporte.
- Hay limitación de intentos: un `429` significa demasiadas peticiones; espera antes de reintentar. Los intentos fallidos de autenticación con token también se limitan por IP.

## Ejemplo completo en PHP

Un script mínimo que lista tus VPS con su estado y su IP principal, usando un token de API:

```php
<?php

// Ejemplo mínimo: lista tus VPS usando un token de API del Manager.
// Requisitos: PHP 8 o superior con la extensión curl.
// Crea el token en el Manager: Acceso API -> Crear token.

const BASE_URL  = 'https://manager.ginernet.com';
const API_TOKEN = 'gcpr_TU_TOKEN'; // mejor desde una variable de entorno

function api(string $method, string $path, ?array $body = null): array
{
    $headers = [
        'Accept: application/json',
        'Authorization: Bearer ' . API_TOKEN,
    ];

    $ch = curl_init(BASE_URL . $path);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }

    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);

    $response = (string) curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $data = json_decode($response, true);
    if (!is_array($data)) {
        $data = [];
    }
    if ($status >= 400) {
        throw new RuntimeException(
            "HTTP $status en $method $path: " . ($data['message'] ?? $response)
        );
    }

    return $data;
}

// El token ya va atado a tu cuenta de cliente: sin login ni contexto.
$result = api('GET', '/api/vps');
foreach ($result['items'] as $vps) {
    printf(
        "#%-5d %-25s %-10s %s\n",
        $vps['id'],
        $vps['name'],
        $vps['powerState'],
        $vps['primaryIpAddress']['ipAddress'] ?? 'sin IP',
    );
}
```

Guárdalo como `listar-vps.php`, pon tu token y ejecútalo con `php listar-vps.php`.

## Buenas prácticas

- **Limita el token por IP**: es la protección más efectiva. Un token restringido a las IPs de tus servidores no sirve de nada si se filtra.
- **Mínimo permiso necesario**: si tu integración solo consulta, crea el token de solo lectura. Deja las operaciones sensibles desactivadas salvo que las necesites.
- **El token, fuera del código**: cárgalo de una variable de entorno o de un gestor de secretos, nunca en el repositorio. Si se te escapa en un commit, revócalo en el momento desde **Acceso API** y crea otro.
- **Un token por integración**: así puedes revocar uno sin romper el resto, y en la columna «Último uso» ves desde qué IP trabaja cada uno.
- **Ojo con las operaciones con coste**: crear VPS, redimensionar o contratar licencias se cobra del saldo prepago de la cuenta en el momento, y los borrados son irreversibles. Prueba tu integración con lecturas antes de automatizar escrituras.

## ¿Conectas un agente de IA?

Si lo que quieres conectar es un agente de IA (Claude, Cursor, etc.), no uses la API REST: el Manager tiene un **servidor MCP** con claves API dedicadas y límites de gasto configurables. Consulta [Despliega VPS con IA: servidor MCP](../general/desplegar-vps-con-ia-servidor-mcp).