Вход через AITunnel (OAuth PKCE)
Ваше приложение получает ключ пользователя AITunnel без ручного копирования: человек входит в аккаунт, видит, какой доступ у него просят, и нажимает «Разрешить».
https://aitunnel.83.141.93.205.nip.io/panel/authorize с callback_url, code_challenge и, при необходимости, scopePOST https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/auth/keys, без авторизации, CORS открытsk-aitunnel-…: запросы к моделям за счёт баланса пользователя, в пределах его лимитаsk-aitunnel-mgmt-… ровно с этими правами: ключи, платежи, пресеты, базы знаний, расходЭто поток OAuth 2.0 authorization code с PKCE (RFC 7636), как у OpenRouter. Регистрировать приложение не нужно, секрета клиента нет. Подходит для ботов, CLI, сайтов и плагинов.
Как это работает
- Приложение создаёт случайный
code_verifier(43–128 символовA–Z a–z 0–9 - . _ ~) и хранит его у себя. Наружу отдаётcode_challenge= base64url(SHA-256(verifier)) без=. - Приложение открывает пользователю страницу согласия с
callback_url,code_challengeи, если нужен ключ управления,scope. - Пользователь входит в AITunnel, видит адрес приложения и список прав и нажимает «Разрешить». Для ключа управления мы попросим подтвердить личность паролем, кодом или passkey. Браузер возвращается на
callback_url?code=…, а при отказе — наcallback_url?error=access_denied. - Приложение отправляет
codeиcode_verifierвPOST /v1/aitunnel/auth/keysи получает ключ. Пользователю приходит письмо о том, что приложение получило доступ.
Шаг 1. Страница согласия
https://aitunnel.83.141.93.205.nip.io/panel/authorize
?callback_url=https://myapp.example.com/aitunnel/callback
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256https://aitunnel.83.141.93.205.nip.io/panel/authorize
?callback_url=https://crm.example.com/aitunnel/callback
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&scope=keys:write%20billing:readcallback_urlhttps:// или http://localhost / 127.0.0.1 (для CLI). Без логина и пароля в адресе и без #фрагмента. Ваши параметры (например, state) сохраняются, code добавляется к нимcode_challengeS256 — base64url(SHA-256(code_verifier)), 43 символа. Для plain — сам verifiercode_challenge_methodS256 (по умолчанию, рекомендуется) или plainscope%20 или + в адресе) или запятую. Без scope — API-ключ// 1. Перед входом: verifier храните у себя, наружу уходит только challenge
const base64url = (bytes) =>
btoa(String.fromCharCode(...bytes))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
const challenge = base64url(new Uint8Array(digest));
sessionStorage.setItem("aitunnel_verifier", verifier);
// 2. Отправьте пользователя на страницу согласия
const url = new URL("https://aitunnel.83.141.93.205.nip.io/panel/authorize");
url.searchParams.set("callback_url", "https://myapp.example.com/aitunnel/callback");
url.searchParams.set("code_challenge", challenge);
url.searchParams.set("code_challenge_method", "S256");
// Нужен ключ управления? Перечислите права:
// url.searchParams.set("scope", "keys:write billing:read");
location.href = url.href;Права (scope)
usage:readkeys:readkeys:writepresets:readpresets:writeknowledge:readknowledge:writebilling:readbilling:writeprofile:readprofile:writeПросите только то, что нужно: каждое право пользователь видит отдельной строкой, а права на деньги и ключи выделены. write включает read той же области. С неизвестным правом страница согласия покажет «Ссылка для входа неверна». Подробно о каждом праве — в ключах управления.
Шаг 2. Обмен кода на ключ
// 3. На странице callback_url: обменяйте code на ключ
const params = new URLSearchParams(location.search);
if (params.get("error") === "access_denied") {
// пользователь нажал «Отказать»
} else {
const res = await fetch("https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/auth/keys", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
code: params.get("code"),
code_verifier: sessionStorage.getItem("aitunnel_verifier"),
code_challenge_method: "S256",
}),
});
const { key, key_type, scopes } = await res.json();
// key_type: "api" — sk-aitunnel-…, "management" — sk-aitunnel-mgmt-… с правами scopes
sessionStorage.removeItem("aitunnel_verifier");
}Тот же запрос из любого языка:
curl https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/auth/keys \
-H "Content-Type: application/json" \
-d '{
"code": "Qm9vZ2llV29vZ2llLi4uY29kZS1mcm9tLWNhbGxiYWNr",
"code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
"code_challenge_method": "S256"
}'{
"key": "sk-aitunnel-AbCdEfGhIjKlMnOpQrStUvWxYz012345",
"key_type": "api",
"scopes": [],
"user_id": 4242,
"key_id": 917,
"name": "myapp.example.com"
}{
"key": "sk-aitunnel-mgmt-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd",
"key_type": "management",
"scopes": ["keys:write", "billing:read"],
"user_id": 4242,
"key_id": 31,
"name": "crm.example.com"
}Пример: сервер бота
Если callback_url ведёт на ваш сервер (Telegram-бот, бэкенд сайта), verifier хранится на сервере, а пользователь приходит по ссылке из чата:
# Сервер приложения (например, Telegram-бота): callback_url ведёт сюда
import base64, hashlib, secrets
import requests
def start_login(state_store, chat_id):
verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(
hashlib.sha256(verifier.encode()).digest()
).rstrip(b"=").decode()
state = secrets.token_urlsafe(16)
state_store[state] = {"verifier": verifier, "chat_id": chat_id}
callback = f"https://bot.example.com/aitunnel/callback?state={state}"
return (
"https://aitunnel.83.141.93.205.nip.io/panel/authorize"
f"?callback_url={requests.utils.quote(callback, safe='')}"
f"&code_challenge={challenge}&code_challenge_method=S256"
)
def on_callback(state_store, state, code):
login = state_store.pop(state)
answer = requests.post(
"https://aitunnel.83.141.93.205.nip.io/__api/v1/aitunnel/auth/keys",
json={"code": code, "code_verifier": login["verifier"]},
timeout=30,
).json()
return login["chat_id"], answer["key"] # сохраните ключ за этим пользователемЧто видит пользователь
- Страница согласия показывает адрес приложения — хост
callback_url—, аккаунт, от имени которого выдаётся ключ, и что ключ сможет и чего не сможет. - Пользователь задаёт ключу название (по умолчанию — хост приложения) и срок: без срока (по умолчанию), 30 дней, 90 дней или 1 год. API-ключу — ещё лимит расходов в рублях.
- Приходит письмо: какое приложение получило доступ и что оно может.
- В разделе API-ключи или на вкладке «Ключи управления» у такого ключа метка с адресом приложения. Удалить или отозвать его можно в любой момент — приложение сразу потеряет доступ.
- Ключ, которым не пользовались 90 дней, ставится на паузу (403) — и API-ключ, и ключ управления приложения. Пользователь возобновляет его одной кнопкой.
Ошибки
invalid_codecode_verifier не подходит. Код сгорает после первой попытки, даже неудачной — начните вход зановоbalance_requiredkeys_limit_reached, management_keys_limit_reachedcallback_url не https, содержит #, логин или пароль, нет code_challenge или в scope неизвестное правоЕсли у пользователя нулевой баланс или не подтверждена почта, API-ключ он выдать не сможет — страница согласия скажет об этом сразу. Ключу управления баланс не нужен.
Безопасность
codeиз адреса бесполезен безcode_verifier: перехватить ключ по ссылке нельзя. ИспользуйтеS256— сplainverifier виден в адресе страницы согласия.- Приложение не регистрируется, поэтому пользователь доверяет адресу, который видит. Показывайте в своём интерфейсе, что вход идёт через AITunnel, и не открывайте страницу согласия без действия пользователя.
- API-ключ видит баланс аккаунта (
GET /aitunnel/balance) и свои запросы, но не может управлять аккаунтом. Ключ управления может только то, что в его правах, и никогда — служебное правоops; войти в кабинет, сменить пароль, почту или способы входа он не может. - Каждое изменение, сделанное ключом управления, записывается в журнал активности аккаунта (Настройки → Безопасность).
- Выдавать ключ может только сам владелец аккаунта: сотрудник поддержки, вошедший в аккаунт, этого сделать не может.