Ключи Management API

Используйте gpm-... ключ Management API с /api/v1/keys, чтобы программно смотреть, создавать, обновлять и удалять обычные gp-... API-ключи, доступные через этот API. Это ключи для служебной автоматизации внутри одного аккаунта GonkaGate. Для /v1/* запросов к моделям они не подходят.

Выберите правильный тип ключа

• Обычные gp-... API-ключи аутентифицируют запросы к /v1/*.
• Ключи Management API gpm-... аутентифицируют маршруты /api/v1/keys*.
• Ключи управления могут управлять только обычными API-ключами того же аккаунта GonkaGate, которые доступны через /api/v1/keys.
• Ключи read_write могут смотреть список, создавать, получать, обновлять и удалять такие ключи.
• Ключи read_only могут только смотреть список и получать отдельный ключ.

Используйте ключи управления, когда нужно:

• выдавать отдельный обычный API-ключ на клиента, workspace или environment
• ротировать или отзывать обычные API-ключи из автоматизации
• управлять индивидуальными USD-лимитами
• разделять staging, production, CI и внутренний трафик

Создайте ключ управления один раз

1. Войдите в dashboard.
2. Откройте панель → настройки → ключи управления.
3. Нажмите Create.
4. Укажите отображаемое название и подтвердите создание.
5. Скопируйте секрет gpm-... и сохраните его в безопасном месте.

Важные правила:

• В текущем dashboard create flow можно указать только отображаемое название. Настроек access mode и срока действия в этом UI нет.
• GonkaGate показывает полный секрет gpm-... только один раз.
• Для создания ключей управления и работы с /api/v1/keys у аккаунта должен быть подтверждённый email.
• На один аккаунт разрешено до 25 активных management keys.
• Для production, staging, CI и внутренних инструментов лучше создавать отдельные ключи управления, а не делить один credential.

Вызывайте /api/v1/keys с ключом gpm-...

В production GonkaGate используйте такой base URL:

https://api.gonkagate.com/api/v1/keys

На другом deployment оставьте /api/v1/keys и замените только host.

Передавайте ключ управления в Bearer header:

Authorization: Bearer gpm-YOUR_MANAGEMENT_KEY

Поддерживаемые операции

hash — это 64-символьный идентификатор из data.hash. Это не сырой gp-... ключ.

Управляйте обычными ключами программно

const MANAGEMENT_API_KEY = "gpm-YOUR_MANAGEMENT_KEY";
const BASE_URL = "https://api.gonkagate.com/api/v1/keys";

const headers = {
Authorization: `Bearer ${MANAGEMENT_API_KEY}`,
"Content-Type": "application/json",
};

const listResponse = await fetch(BASE_URL, { headers });

const listWithDisabledResponse = await fetch(
`${BASE_URL}?offset=100&include_disabled=true`,
{ headers },
);

const createResponse = await fetch(BASE_URL, {
method: "POST",
headers,
body: JSON.stringify({
name: "Customer Production Key",
limit: 50,
limit_reset: "monthly",
expires_at: "2026-12-31T23:59:59Z",
}),
});

const created = await createResponse.json();
const keyHash = created.data.hash;

const getResponse = await fetch(`${BASE_URL}/${keyHash}`, { headers });

const updateResponse = await fetch(`${BASE_URL}/${keyHash}`, {
method: "PATCH",
headers,
body: JSON.stringify({
name: "Customer Production Key v2",
disabled: true,
limit: null,
expires_at: null,
}),
});

const deleteResponse = await fetch(`${BASE_URL}/${keyHash}`, {
method: "DELETE",
headers,
});

После создания сохраните оба значения:

• key — одноразовый сырой секрет нового обычного gp-... API-ключа.
• data.hash — 64-символьный внешний идентификатор для GET, PATCH и DELETE.

Правила запросов, которые меняют поведение

Runtime-лимиты для созданных здесь ключей

limit — это USD-лимит расходов, а не лимит пропускной способности. Когда обычный gp-... ключ, созданный через /api/v1/keys, используется на /v1/* запросах к моделям, GonkaGate проверяет и bucket самого ключа, и bucket аккаунта-владельца. Если любой bucket исчерпан, запрос может вернуть 429 rate_limit_exceeded.

Текущие production-лимиты GonkaGate для аутентифицированных /v1/* запросов к моделям:

RPM означает requests per minute. Burst — это отдельное 10-секундное окно запросов. Token windows сейчас учитываются для телеметрии и headers: 2,000,000 TPM для обычного API-ключа и key+IP scopes, и 10,000,000 TPM для аккаунта-владельца и source IP scopes. Сами token windows сегодня не блокируют запросы.

В схеме на 500-1000 customer keys под одним аккаунтом GonkaGate каждый customer key получает собственный per-key bucket, но все эти ключи всё равно делят bucket аккаунта-владельца и общий prepaid USD balance аккаунта. Management keys не создают отдельные runtime buckets для /v1/*.

Что возвращают успешные вызовы

Успешные вызовы /api/v1/keys используют OpenRouter-style field names:

• GET /api/v1/keys: { data: OpenRouterKey[] }
• GET и PATCH /api/v1/keys/:hash: { data: OpenRouterKey }
• POST /api/v1/keys: { key: "gp-...", data: OpenRouterKey }
• DELETE /api/v1/keys/:hash: { deleted: true }

Все limit* и usage* значения выражены в USD.

{
  "hash": "4f2f5b6f0b0e16eab8c2e55d4f2f0ce4c6f5b91f2a28f8e93b0f8c3b8b112233",
  "label": "gp-AbCd...WXYZ",
  "name": "Customer Production Key",
  "disabled": false,
  "limit": 50,
  "limit_remaining": 50,
  "limit_reset": "monthly",
  "usage": 0,
  "usage_daily": 0,
  "usage_weekly": 0,
  "usage_monthly": 0,
  "created_at": "2026-03-16T10:00:00.000Z",
  "updated_at": "2026-03-16T10:00:00.000Z",
  "expires_at": "2026-12-31T23:59:59.000Z"
}

Частые ошибки

Даже на OpenRouter-совместимом маршруте ошибки остаются в стандартном GonkaGate /api/* error envelope:

{
  "success": false,
  "error": {
    "message": "Management API key is read-only",
    "statusCode": 403,
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T10:00:00.000Z"
  }
}

См. также

• Обработка ошибок API, когда автоматизация выходит в прод и нужны понятные retry boundaries, request ID и support-ready сценарий разбора сбоев.
• Аутентификация и API-ключи для обычных gp-... ключей на /v1/*.
• Быстрый старт, если нужен первый запрос к модели, а не автоматизация управления ключами.
• Обзор справочника API для публичного /v1 контракта после того, как ключи уже выдаются автоматически.