Управление API-ключами

Методы

API-ключ эти методы не вызывает, даже для самого себя: свои настройки он читает через GET /aitunnel/key. Что значат бюджет, срок и списки, с примерами из кабинета, — в статье API-ключи.

Список ключей

curl https://api.aitunnel.ru/v1/aitunnel/keys \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

{
  "data": [
    {
      "id": 4217,
      "name": "Прод-бот",
      "hint": "sk-aitunnel-…x7Qp",
      "paused_at": null,
      "pause_reason": null,
      "expires_at": "2027-01-01T00:00:00.000Z",
      "budget": {
        "limit": 500,
        "spent": 120.4,
        "remaining": 379.6,
        "period": "monthly",
        "resets_at": "2026-11-30T21:00:00.000Z",
        "alert": true,
        "alert_email": "ops@example.com"
      },
      "allowed_models": ["gpt-5.4-mini", "support-bot"],
      "allowed_ips": ["203.0.113.10", "2001:db8::/32"],
      "redaction": {
        "mode": "mask",
        "types": ["email", "phone"],
        "dictionary": [
          { "word": "Проект Икс", "replacement": "проект" }
        ]
      },
      "log_days": 7,
      "spent_total": 1840.25,
      "last_used_at": "2026-11-14T08:12:44.000Z",
      "secret_rotated_at": null,
      "created_at": "2026-10-01T10:00:00.000Z",
      "updated_at": "2026-11-02T15:20:11.000Z"
    }
  ]
}

Ключи идут от старых к новым. Удалённых в списке нет. GET /keys/{id} возвращает один такой объект.

Создать ключ

curl -X POST https://api.aitunnel.ru/v1/aitunnel/keys \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Прод-бот",
    "budget": { "limit": 500, "period": "monthly", "alert": true },
    "expires_at": "2027-01-01T00:00:00Z",
    "allowed_models": ["gpt-5.4-mini", "support-bot"],
    "allowed_ips": ["203.0.113.10"]
  }'

Ответ 201 — объект ключа и поле secret:

{
  "id": 4217,
  "name": "Прод-бот",
  "hint": "sk-aitunnel-…x7Qp",
  "paused_at": null,
  "pause_reason": null,
  "expires_at": "2027-01-01T00:00:00.000Z",
  "budget": {
    "limit": 500,
    "spent": 0,
    "remaining": 500,
    "period": "monthly",
    "resets_at": "2026-11-30T21:00:00.000Z",
    "alert": true,
    "alert_email": null
  },
  "allowed_models": ["gpt-5.4-mini", "support-bot"],
  "allowed_ips": ["203.0.113.10"],
  "redaction": {
    "mode": null,
    "types": ["email", "phone", "passport", "snils", "inn", "ogrn", "ogrnip", "credit_card", "jwt", "secret", "address", "person"],
    "dictionary": []
  },
  "log_days": null,
  "spent_total": 0,
  "last_used_at": null,
  "secret_rotated_at": null,
  "created_at": "2026-11-14T13:16:00.000Z",
  "updated_at": "2026-11-14T13:16:00.000Z",
  "secret": "sk-aitunnel-EXAMPLEexampleEXAMPLEexamplex7Qp"
}

• Обязательно только name: получится ключ без бюджета, срока и ограничений.
• Поле, которого метод не знает, — ошибка 400, а не пропуск: опечатка в budget не оставит ключ без бюджета.
• Ключ можно создать при положительном балансе и подтверждённой почте.
• Число ключей ограничено: один ключ и ещё по одному за каждые полные 1 000 ₽ баланса. Сверх лимита — 409.

Изменить ключ

PATCH /keys/{id} принимает те же поля, что создание. Меняется только то, что передано; остальное остаётся. Ответ — объект ключа.

curl -X PATCH https://api.aitunnel.ru/v1/aitunnel/keys/4217 \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": { "limit": 1000 },
    "allowed_ips": null
  }'

• null или пустой список снимает ограничение: "allowed_ips": null — ключ работает с любого адреса.
• Истёкший ключ продлевается новым expires_at. Секрет и настройки прежние.
• Новые правила действуют со следующего запроса с этим ключом.

Бюджет

Бюджет — сколько ключ может потратить за период. Исчерпан — запросы к моделям с этим ключом получают 402 с типом budget_exceeded.

• Сброс привязан к календарю по московскому времени: daily — в 00:00, weekly — в ночь на понедельник, monthly — в ночь на 1-е число.
• Новый limit сохраняет потраченное: подняли лимит с 500 до 1 000 ₽ при расходе 120 ₽ — осталось 880 ₽.
• В PATCH можно передать budget.remaining — сколько осталось в текущем периоде. Потраченное станет limit − remaining. Остаток больше лимита — 400.
• Другой period пересчитывает resets_at; тот же период границу не сдвигает.
• "budget": null убирает бюджет вместе с периодом и письмом.

Сбросить секрет

POST /keys/{id}/rotate выдаёт ключу новый секрет. Ответ — объект ключа и secret, как при создании. Старый секрет перестаёт работать сразу: запросы с ним получают 401. Имя, бюджет, расход, ограничения и пауза остаются.

curl -X POST https://api.aitunnel.ru/v1/aitunnel/keys/4217/rotate \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Пауза и возобновление

POST /keys/{id}/pause отключает ключ: запросы с ним получают 403 «Этот API-ключ приостановлен владельцем». Секрет, бюджет и настройки сохраняются. POST /keys/{id}/resume включает ключ обратно, в том числе поставленный на паузу автоматически после 90 дней без запросов. Оба метода без тела, ответ — объект ключа.

Дублировать

POST /keys/{id}/duplicate с телом { "name": "…" } создаёт новый ключ с настройками исходного. Ответ 201 — объект нового ключа и его secret.

• Копируются бюджет, модели, IP, защита данных и срок хранения логов.
• Расход не переносится: бюджет нового ключа полный.
• Срок переносится как длительность: ключ, созданный на 30 дней, даёт копию на 30 дней от текущего момента.
• Копия занимает место в лимите ключей, как обычный новый ключ.

Скопировать настройки

POST /keys/{id}/copy-settings переносит группы настроек ключа {id} на другие ключи аккаунта.

curl -X POST https://api.aitunnel.ru/v1/aitunnel/keys/4217/copy-settings \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key_ids": [4218, 4219],
    "groups": ["budget", "models"]
  }'

key_ids — до 500 номеров ключей, groups — какие группы копировать:

• Ответ — { "data": [...] } с изменёнными ключами.
• Всё или ничего: если хотя бы один номер не действующий ключ аккаунта, ответ 404 и ни один ключ не меняется.
• Имя, секрет, срок и пауза не копируются.
• Потраченное у каждого ключа своё: получив бюджет, ключ сохраняет свой расход за период, а если бюджета не было — начинает с нуля.

Удалить ключ

DELETE /keys/{id} отвечает 204 без тела. Ключ перестаёт работать со следующего запроса: 401 «Этот API-ключ удалён». Восстановить его нельзя; статистика и логи его запросов остаются.

Мой IP

GET /keys/my-ip отвечает { "ip": "203.0.113.10" } — адрес, с которого пришёл запрос, каким его сравнивает список allowed_ips. За зеркалом ru-api.aitunnel.ru это ваш адрес, а не адрес зеркала. null, если адрес определить не удалось.

Ошибки

{
  "error": {
    "code": 400,
    "type": "invalid_request",
    "message": "Поле «budget.remaining»: Остаток не может быть больше лимита",
    "metadata": {
      "fields": [
        {
          "field": "budget.remaining",
          "message": "Остаток не может быть больше лимита"
        }
      ]
    },
    "request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
  }
}

Каждое изменение, сделанное ключом управления, видно владельцу в журнале активности.