В проекте два разных API

Не путайте их — они решают разные задачи.

Быстрый старт

⚡ Instant setup — одна команда на сервере

1. Copy-paste snippet в модалке

После создания интеграции открывается модальное окно с тремя табами: API key, Quick Start, Docs. В Quick Start выберите карточку вашей платформы — там уже подставлены ваши client_id, redirect_uri, discovery URL и (один раз) client_secret. Копируете в настройки — готово:

• 🛡️ oauth2-proxy — docker-compose, защищает ЛЮБОЙ веб-сервис (Grafana, Prometheus, внутренние дашборды и т.п.)
• 🦊 Gitea — одна команда CLI, без перезапуска
• 📊 Grafana — готовый блок для grafana.ini
• ☁️ Nextcloud — конфиг для OpenID Connect Login app
• 🟢 Node.js / Express — 40 строк с openid-client + PKCE
• 🐍 Python / FastAPI — authlib + starlette-session
• 🌐 curl — для отладки или языков без OIDC-библиотеки
• 🔌 Generic OIDC — все 4 URL для любой платформы (Keycloak, Auth0, AWS Cognito, Azure AD, Okta как identity broker и т.д.)

2. One-command installer

Максимально быстрый вариант. Одна команда на вашем сервере — ставит oauth2-proxy как systemd-сервис, пишет конфиг с нашими endpoint'ами:

bashCopyexport NFT_CLIENT_SECRET='pk_live_...'
curl -fsSL https://phantomnumbers.org/integrate/<slug>.sh | bash

Нужно:

• Ubuntu / Debian с systemd, root
• Ваш NFT_CLIENT_SECRET в env (скрипт его не хранит — тянет из окружения)

Что делает:

• Скачивает официальный oauth2-proxy v7.6.0 (amd64/arm64)
• Создаёт системного юзера oauth2proxy
• Пишет /etc/oauth2-proxy.cfg + systemd unit, запускает
• Слушает на 0.0.0.0:4180, форвардит в UPSTREAM (по умолчанию localhost:8080, можно переопределить env)

После этого ставите nginx / Caddy → 127.0.0.1:4180 — и ваш сервис за логином NFT Number.

3. Docker-compose

Если у вас docker-окружение:

bashCopycurl -fsSL "https://phantomnumbers.org/integrate/<slug>/oauth2-proxy.yml" > docker-compose.yml
# отредактируйте OAUTH2_PROXY_UPSTREAMS под ваш сервис
export NFT_CLIENT_SECRET='pk_live_...'
export COOKIE_SECRET="$(openssl rand -base64 32)"
docker compose up -d

Как это работает

Пользователь вводит свой NFT-номер (формат 111-22-101-18) на вашем сайте. Вы вызываете наш /api/request-code с его номером и вашим API-ключом. Мы:

• находим владельца в нашей БД;
• генерируем 6-значный OTP (TTL 10 мин);
• доставляем по трём каналам: Telegram-бот, Web Push, live-уведомление в открытом webapp;
• в сообщении всегда указано имя вашей интеграции.

Пользователь вводит код у вас, вы вызываете /api/verify-code — мы возвращаем id_token и опционально refresh_token.

API endpoints

Два способа встроить вход — выбирайте под себя:

Заголовок аутентификации для простого API: X-API-Key: pk_live_.... Для OAuth2 — см. раздел ниже.

OAuth 2.0 / OpenID Connect

Стандартный authorization-code flow. Подходит когда вы не хотите принимать номер и OTP у себя на фронте — мы показываем consent-страницу сами, возвращаем code, вы обмениваете его на токены.

Шаги flow

https://phantomnumbers.org/api/authorize
  ?response_type=code
  &client_id=<ваш slug>
  &redirect_uri=<URL в allowed_redirect_uris>
  &scope=openid%20profile%20email
  &state=<случайная строка для CSRF>
  &nonce=<случайная строка для id_token>
  &code_challenge=<BASE64URL(SHA-256(verifier))>
  &code_challenge_method=S256

POST /api/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=ac_...
&redirect_uri=<тот же URI>
&client_id=<slug>
&client_secret=<ваш API key pk_live_...>
&code_verifier=<сохранённый на шаге 2>

GET /api/userinfo
Authorization: Bearer <access_token>

→ {"sub":"123","email":"[email protected]",
   "nft_number":"1112210118","preferred_username":"1112210118",
   "name":"...","ton_wallet":"0:..."}

PKCE — обязателен для всех клиентов

С апреля 2026 PKCE (RFC 7636, method=S256) требуется на /api/authorize для всех приложений — и backend-интеграций с client_secret, и SPA без секрета. Это закрывает атаку «украденный auth-code → обмен на токен одним лишь client_id». Минимальный TypeScript-snippet:

const verifier = crypto.randomUUID().replace(/-/g, '') + crypto.randomUUID().replace(/-/g, '');
const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
const challenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
sessionStorage.setItem('pkce_verifier', verifier);
location.assign(`/api/authorize?...&code_challenge=${challenge}&code_challenge_method=S256`);

Что получит ваш сервис в userinfo

Готовые клиенты, протестированные с нами

• Gitea — Site Administration → Authentication Sources → Add → OAuth2 provider = OpenID Connect, Discovery URL = наш openid-configuration. 3 минуты настройки.
• oauth2-proxy — провайдер oidc, указать --oidc-issuer-url=https://phantomnumbers.org. Можно защитить любой non-OIDC сервис за этим прокси.
• Grafana — Generic OAuth в [auth.generic_oauth], указать endpoints из discovery.

id_token: HS256 или RS256

Алгоритм подписи выбирается при создании интеграции:

• HS256 — shared secret. Секрет = ваш API-ключ (он уже есть у обеих сторон). Самый простой вариант: одной функцией подписал, одной проверил. Ключ обязан оставаться на бэкенде.
• RS256 — асимметричный. Мы подписываем приватным ключом, вы валидируете публичным из /.well-known/nft-numbers.jwks. Совместимо с любыми OIDC-библиотеками, подходит для раздачи токенов в мобильные приложения.

Payload: {iss, sub, aud, iat, exp, number, telegram_username?, wallet?, scope?}. TTL — 1 час (настраивается env ID_TOKEN_LIFETIME_SEC).

Refresh tokens

Вместе с id_token возвращается refresh_token (30 дней). Обменять на новую пару:

curlCopycurl -X POST https://phantomnumbers.org/api/refresh-token \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"rt_..."}'

На каждом обмене старый refresh инвалидируется, выдаётся новый (rotation). Выдачу refresh можно отключить в настройках интеграции.

Webhooks

Укажите webhook_url в настройках интеграции — на него будут POST'иться события:

• login.requested — OTP сгенерирован
• login.verified — OTP подтверждён
• login.denied — пользователь нажал «Это не я»
• integration.suspended / integration.resumed

Подпись в заголовке X-NFT-Numbers-Signature: sha256=<hmac>. Всегда проверяйте подпись до обработки payload.

Пример на JavaScript

Frontend (вызывает ваш бэкенд)

htmlCopy<button id="loginBtn">Sign in with NFT Number</button>
<script>
document.getElementById('loginBtn').addEventListener('click', async () => {
  const phone = prompt("Ваш NFT-номер (111-22-101-18):");
  await fetch("/auth/nft/request", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({ phone })
  });
  const code = prompt("Проверьте Telegram или webapp. Введите код:");
  const r = await fetch("/auth/nft/verify", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({ phone, code })
  });
  if (r.ok) location.reload();
  else alert("Неверный код");
});
</script>

Backend (Node.js / Express)

javascriptCopyconst API = "https://phantomnumbers.org";
const KEY = process.env.NFT_NUMBERS_API_KEY;

app.post("/auth/nft/request", async (req, res) => {
  const r = await fetch(API + "/api/request-code", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": KEY },
    body: JSON.stringify({ phone: req.body.phone })
  });
  res.status(r.status).json(await r.json());
});

app.post("/auth/nft/verify", async (req, res) => {
  const r = await fetch(API + "/api/verify-code", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-API-Key": KEY },
    body: JSON.stringify({ phone: req.body.phone, code: req.body.code })
  });
  const data = await r.json();
  if (!data.success) return res.status(401).json(data);
  req.session.userId = data.user.id;
  req.session.nftNumber = data.user.number;
  res.json({ ok: true });
});

Пример на Python

pythonCopyimport os, httpx, jwt

API = "https://phantomnumbers.org"
KEY = os.environ["NFT_NUMBERS_API_KEY"]

async def request_code(phone: str) -> None:
    async with httpx.AsyncClient() as c:
        r = await c.post(f"{API}/api/request-code",
                         headers={"X-API-Key": KEY},
                         json={"phone": phone})
        r.raise_for_status()

async def verify(phone: str, code: str) -> dict | None:
    async with httpx.AsyncClient() as c:
        r = await c.post(f"{API}/api/verify-code",
                         headers={"X-API-Key": KEY},
                         json={"phone": phone, "code": code})
        if r.status_code != 200:
            return None
        j = r.json()
        if not j.get("success"):
            return None
        # HS256 (shared secret = API-ключ):
        claims = jwt.decode(
            j["id_token"], key=KEY,
            algorithms=["HS256"],
            audience="your-integration-slug",
        )
        return {"user": j["user"], "claims": claims,
                "refresh_token": j.get("refresh_token")}

curl

bashCopy# Запросить OTP
curl -X POST https://phantomnumbers.org/api/request-code \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_..." \
  -d '{"phone":"1112210118"}'

# Подтвердить OTP → получить id_token
curl -X POST https://phantomnumbers.org/api/verify-code \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_..." \
  -d '{"phone":"1112210118","code":"482193"}'

Безопасность и rate-limits

• Per-integration: по умолчанию 100 req/h (настраивается админом). Sandbox — 10/h.
• Per-phone recipient: 3 OTP в час на номер (защита владельца от спама).
• Per-IP: глобальный throttle.
• Abuse score: каждый «Это не я» инкрементит счётчик; при достижении threshold (5 по умолчанию) — авто-suspend.
• Scope escalation: user.identity.wallet / user.identity.telegram выдаются только после одобрения админа.
• Identity window: GET /api/identity/user/{phone} требует успешный verify для этой пары (integration, phone) за последние 30 мин.
• Redirect URI: если в настройках интеграции заполнен allowed_redirect_uris, передать можно только exact-match URI.

Billing

Платформа может быть бесплатной, по подписке, pay-per-verification или pay-per-RPM — режим выбирает админ в Platform Settings. В платном режиме в Developer Panel появляется кнопка Pay with TON: открывается deep-link ton://transfer/<wallet>, после on-chain подтверждения баланс пополняется автоматически.

Следующий шаг

Открыть Developer Panel → + New Integration — получите первый API-ключ за минуту.