Автентифікація

Railhook приймає чотири види облікових даних. Ця сторінка пояснює, який із них використовувати, як його отримати і як замінити, не зламавши тих, хто ним користується.

Облікові дані	Хто використовує	Як передаються	Що несуть
Токен доступу (JWT)	Панель і все, що діє від імені людини	Authorization: Bearer …	Користувача, його організацію, його роль
API-ключ	Ваші сервери та SDK	X-API-Key: …	Один проєкт і область дії
Код пристрою	railhook login у CLI	Обмінюється на сесію	Те саме, що токен доступу
Токен адміністратора платформи	Той, хто експлуатує розгортання	X-Platform-Admin-Token: …	Доступ до /api/v1/admin/** у всіх організаціях

Токени доступу

Увійдіть через POST /api/v1/auth/login. Тіло відповіді містить accessToken. Токена оновлення в тілі немає: його встановлено як HttpOnly-cookie з назвою refresh_token і шляхом /api/v1/auth.

cURL

curl -X POST https://railhook.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"[email protected]","password":"••••••••"}'

Node.js

const res = await fetch('https://railhook.example.com/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[email protected]', password: process.env.PASSWORD }),
});
const { accessToken } = await res.json();

Python

import os

import requests

res = requests.post(
    "https://railhook.example.com/api/v1/auth/login",
    json={"email": "[email protected]", "password": os.environ["PASSWORD"]},
)
access_token = res.json()["accessToken"]

Передавайте токен доступу в кожному запиті, що діє від імені цього користувача:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Час життя та оновлення

Токен	Час життя за замовчуванням
Токен доступу	15 хвилин
Токен оновлення	24 години

POST /api/v1/auth/refresh читає cookie refresh_token, а якщо cookie немає — поле refreshToken у JSON-тілі. Він повертає новий токен доступу й встановлює нове cookie оновлення. Витрачений токен оновлення потрапляє до чорного списку.

Повторно використаний токен оновлення завершує всі сесії

Якщо пред’явити вже витрачений токен оновлення, Railhook відкликає всі токени цього користувача. Саме так виглядає викрадений токен, тож до нього так і ставляться.

Кожен вхід — це сесія. Користувач може переглянути свої сесії, закрити одну або закрити всі. POST /api/v1/auth/logout відкликає поточні токени доступу та оновлення.

Невдалі входи

Вхід обмежено за частотою, а повторні невдачі на якийсь час блокують обліковий запис. Обидва механізми налаштовуються через змінні середовища:

Змінна	За замовчуванням	Значення
AUTH_RATE_LIMIT_LOGIN_PER_MINUTE	10	Спроб входу на IP і на email за хвилину. Понад це API відповідає 429.
AUTH_LOCKOUT_ENABLED	true	Вмикає або вимикає блокування
AUTH_LOCKOUT_THRESHOLD	5	Невдач поспіль до першого блокування
AUTH_LOCKOUT_INITIAL_SECONDS	60	Перше блокування. Подвоюється з кожною наступною невдачею.
AUTH_LOCKOUT_MAX_SECONDS	900	Найдовше блокування
AUTH_LOCKOUT_FAILURE_WINDOW_MINUTES	60	За який період рахуються невдачі

Блокування спливає саме, а скидання пароля знімає його одразу.

API-ключі

API-ключ належить одному проєкту. Ним надсилають події, і на ньому побудовані SDK.

1. Створіть ключ для проєкту в панелі або через POST /api/v1/projects/{projectId}/api-keys.

2. Скопіюйте key з відповіді. Його показують один раз: Railhook зберігає лише хеш, тож загублений ключ не відновити, лише замінити.

3. Покладіть його у змінну середовища на сервері, який ви контролюєте, і передавайте в заголовку X-API-Key:

   X-API-Key: Kz1uAIM8VeJUQN7yGSYCst64WxNLabBHfOYbrPlJ1yk

Області дії та строк

Область дії	Дозволяє
READ_WRITE	Читання й запис. Надсилання події — це запис. За замовчуванням.
READ_ONLY	Лише читання. Запис відповідає 403.

Ключ може мати дату expiresAt. Після неї, або коли ключ відкликано, він більше нічого не автентифікує. Відкликання діє негайно, без пільгового періоду.

Небезпечно

Ключ у клієнтському коді чи в репозиторії може використати будь-хто, хто його прочитає. Тримайте ключі лише на серверах.

Ротація ключа без простою

POST /api/v1/projects/{projectId}/api-keys/{apiKeyId}/rotate створює заміну з тією самою назвою та областю дії. Старий ключ працює ще впродовж пільгового вікна, тож ви встигнете розгорнути новий усюди, перш ніж старий перестане діяти.

Поле	За замовчуванням	Значення
gracePeriodHours	24	Скільки ще працює старий ключ. 0 відрізає його одразу — таку ротацію роблять після витоку.
expiresAt	немає	Необов’язковий строк дії нового ключа

Ротація ніколи не подовжує старий ключ: якщо він мав спливти раніше, ця дата лишається. Ключ можна ротувати один раз. Щоб ротувати знову, ротуйте його заміну.

Вхід у CLI

railhook login використовує код пристрою. CLI показує URL і код, ви підтверджуєте код у панелі, і CLI отримує власну сесію. Див. CLI.

Токен адміністратора платформи

PLATFORM_ADMIN_TOKEN — облікові дані для операторських ендпоінтів /api/v1/admin/**. Він не залежить від організацій: OWNER організації його не має. Залиште змінну порожньою, і адмінські ендпоінти лишаться недоступними. Встановлюйте її лише тоді, коли оператору вони потрібні, і передавайте токен у заголовку X-Platform-Admin-Token.

Форми запитів і відповідей для кожного ендпоінта автентифікації — у довіднику API.

Вхід через Google

Кнопка «Продовжити з Google» з’являється на сторінках входу й реєстрації, щойно розгортання має OAuth-клієнт Google. Одна кнопка робить обидві речі:

• Для облікового запису Google, якому не відповідає жоден обліковий запис Railhook, він створюється одразу: адреса позначена підтвердженою, і є власна організація. Для Google Workspace організація називається за доменом (acme.com стає Acme), для особистого облікового запису — «Ім’я»’s workspace. Назву можна змінити в налаштуваннях організації.
• Обліковий запис, зареєстрований з паролем на ту саму адресу, отримує Google як другий спосіб входу. Пароль і далі працює.
• Відповідність шукається за постійним ідентифікатором людини в Google, тож зміна адреси в обліковому записі Google веде до того самого облікового запису Railhook.

Обліковий запис, створений через Google, не має пароля. Щоб додати його, скористайтеся «Забули пароль?» на сторінці входу.

1. У Google Cloud Console створіть OAuth client ID типу Web application.

2. Додайте дозволений redirect URI. Це ваш APP_BASE_URL плюс шлях callback, і він має збігатися точно:

   https://railhook.example.com/api/v1/auth/oauth/google/callback

   Для локального стеку на порту 8080 додайте також http://localhost:8080/api/v1/auth/oauth/google/callback.

3. На OAuth consent screen залиште лише області openid, email і profile.

4. Задайте обидва значення для API і перезапустіть його:

   GOOGLE_OAUTH_CLIENT_ID=1234567890-abc.apps.googleusercontent.com
   GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-...

   У Kubernetes задайте googleSignIn.clientId, а секрет покладіть у Secret, названий у googleSignIn.existingSecret.

Заувага

Браузер ніколи не бачить токен в URL. Після Google API перенаправляє на дашборд з одноразовим кодом, який діє один раз протягом 60 секунд, і дашборд обмінює його на сесію через POST /api/v1/auth/oauth/exchange.

Що далі

Організації та роліЩо може кожна роль і кожна область дії ключа.

Помилки та лімітиЩо означають 401, 403 чи 429 і що робити далі.

Надішліть перший вебхукНадішліть подію своїм API-ключем.