Ключи Management API

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

Ограничение совместимости /api/v1/keys работает только с обычными ключами, у которых уже есть внешний data.hash. Старые ключи могут не появляться в списке и не находиться по :hash. Если такой ключ нужно вести через этот API, создайте новый или ротируйте текущий.

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

• Обычные 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. Откройте Management Keys.
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.

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

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

Успешные вызовы /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/*.
• Quickstart, если нужен первый запрос к модели, а не автоматизация управления ключами.
• Обзор API Reference для публичного /v1 контракта после того, как ключи уже выдаются автоматически.