Integrate your software with the Manager API

The Manager API is the same one the panel itself uses: everything you can do from the web (create and manage VPS, power them on and off, firewall, IPs, backups, billing, tickets...) is available as HTTP calls with JSON responses, ready to integrate into your own software.

The interactive reference

With your Manager session open, visit https://manager.ginernet.com/api: it is the full client API reference (Swagger UI), with 300+ operations organised by category, each with its parameters, request body and responses. You can even try real calls there with your own session.

The machine-readable OpenAPI specification lives at https://manager.ginernet.com/api/doc.json: import it into Postman or generate a client for your language with tools like openapi-generator. It is reachable with a session or with an API token.

Authentication: API tokens (recommended)

The recommended way to authenticate your integration is an API token: a credential bound to your client account, sent on every request in the Authorization header. No username, no password, no 2FA, no cookies.

Tokens are created in the Manager under API access (side menu). When creating one you choose:

• Allowed IPs (recommended): a list of IPs or CIDR ranges the token may be used from. Any request from another IP is rejected, so a leaked token is useless outside your servers.
• Read-only: the token can only read information; no writes.
• Sensitive operations: by default a token can not run operations classified as sensitive (revealing credentials, managing accesses, ownership transfers...). Enable it only if your integration needs it.
• Optional expiry.

The token is shown exactly once at creation (it starts with gcpr_); store it in a secrets manager. Using it is one header:

curl -H 'Authorization: Bearer gcpr_YOUR_TOKEN' https://manager.ginernet.com/api/vps

With a token there is no session and no context to select: the token already knows which client it belongs to, and writes do not need the Origin header (that protection is for cookie sessions).

If a call returns 401 with a token, the token is invalid, expired, revoked, or coming from an IP that is not allowed (the message says which). A 403 means the operation exists but that token cannot run it (it is read-only, or the operation is sensitive and the token does not allow it).

Alternative: cookie-based session

The API also accepts the same session the panel uses, meant for trying calls from the interactive reference. The flow, in case you need it:

1. POST /api/auth/login with {"identifier": "...", "password": "..."}. Store the cookies from the response and resend them on every call. If the user has a passkey or TOTP, login requires the second factor (step other than complete), which a script cannot complete in the passkey case.
2. Every write (POST, PUT, PATCH, DELETE) must carry the Origin: https://manager.ginernet.com header (CSRF protection).
3. Select the active client before operating services: GET /api/me returns accessibleClients and POST /api/auth/context with {"clientId": <id>} selects it.
4. The session expires after 60 minutes of inactivity: on a 401, log in again.

For real integrations, use tokens: they do not depend on passwords, never expire from inactivity, and can be restricted by IP and permissions.

How the API is organised

Operations are grouped by category. The main ones:

The complete, per-operation list is in the interactive reference.

Asynchronous operations: tasks

Anything that is not immediate (creating a VPS, resizing, reinstalling, taking a backup...) returns a task. The response includes its id; poll GET /api/tasks/{id} until status is succeeded or failed. Poll every 10-20 seconds, not in a tight loop.

Errors and limits

• 4xx errors return {"message": "..."}, sometimes with code and details. A 404 also means the resource does not belong to your client.
• 5xx errors return a generic message with an errorId: save it and include it if you open a support ticket.
• Rate limits apply: a 429 means too many requests; back off before retrying. Failed token authentication attempts are also rate-limited per IP.

Complete PHP example

A minimal script that lists your VPS with their state and primary IP, using an API token:

<?php

// Minimal example: list your VPS using a Manager API token.
// Requirements: PHP 8+ with the curl extension.
// Create the token in the Manager: API access -> Create token.

const BASE_URL  = 'https://manager.ginernet.com';
const API_TOKEN = 'gcpr_YOUR_TOKEN'; // better from an environment variable

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 on $method $path: " . ($data['message'] ?? $response)
        );
    }

    return $data;
}

// The token is already bound to your client account: no login, no context.
$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'] ?? 'no IP',
    );
}

Save it as list-vps.php, set your token and run it with php list-vps.php.

Good practices

• Restrict the token by IP: the most effective protection. A token limited to your servers' IPs is useless if leaked.
• Least privilege: if your integration only reads, create a read-only token. Leave sensitive operations disabled unless you need them.
• Keep the token out of your code: load it from an environment variable or a secrets manager, never commit it. If it slips into a commit, revoke it immediately under API access and create a new one.
• One token per integration: you can revoke one without breaking the rest, and the "Last used" column shows which IP each one works from.
• Mind operations that cost money: creating VPS, resizing or purchasing licenses is charged to the account's prepaid balance immediately, and deletions are irreversible. Test your integration with reads before automating writes.

Connecting an AI agent?

If what you want to connect is an AI agent (Claude, Cursor, etc.), do not use the REST API: the Manager has an MCP server with dedicated API keys and configurable spend limits. See Deploy VPS with AI: MCP server.