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

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. Токена оновлення в тілі немає: його встановлено як cookie HttpOnly з назвою refresh_token і шляхом /api/v1/auth. Cookie має атрибут Secure, коли APP_ENV=production або APP_BASE_URL починається з https://, і SameSite=Strict у продакшні (Lax в інших випадках).

cURL

curl -X POST https://railhook.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"you@company.com","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: 'you@company.com', 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": "you@company.com", "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 оновлення. Використаний токен оновлення потрапляє до чорного списку. Якщо оновлення завершилося з 429 або 5xx, панель керування пробує ще раз, а виходить із сесії, лише коли відхилено саму сесію.

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

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

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

Невдалі спроби входу

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

Змінна	Типово	Що означає
AUTH_RATE_LIMIT_LOGIN_PER_MINUTE	10	Скільки спроб входу за хвилину дозволено з однієї IP-адреси і для одного email. Понад цей ліміт API відповідає 429.
AUTH_RATE_LIMIT_REFRESH_PER_TOKEN_PER_MINUTE	30	Скільки разів за хвилину можна оновити сесію одним токеном оновлення. Оновлення має власний ліміт і не витрачає ліміт входу.
AUTH_RATE_LIMIT_REFRESH_PER_IP_PER_MINUTE	600	Скільки оновлень сесії за хвилину дозволено з однієї IP-адреси
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	Лише читання. На запит на запис API відповідає 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.

Зміна адреси електронної пошти

Відкрийте Налаштування → Профіль → Змінити email. Що буде далі, залежить від того, чи підтверджено поточну адресу облікового запису.

• Ще не підтверджено. Адреса змінюється одразу, і на неї надходить нове посилання для підтвердження. Посилання, надіслане на стару адресу, перестає працювати. Доки нову адресу не підтверджено, обліковий запис лишається непідтвердженим, з тими самими обмеженнями. Якщо в розгортанні ввімкнено CAPTCHA, під час зміни адреси її доведеться пройти, як і під час реєстрації. Банер із проханням підтвердити адресу пропонує ту саму форму за посиланням Помилилися в адресі? Змініть її.
• Підтверджено. Введіть пароль. В облікового запису, який входить лише через Google, пароля немає: увійдіть через Google ще раз і змініть адресу протягом 10 хвилин. Нічого не зміниться, доки хтось не відкриє посилання, надіслане на нову адресу. На стару адресу надходить повідомлення з посиланням Це не я, яке скасовує зміну. До підтвердження в налаштуваннях видно адресу, що чекає на підтвердження, і кнопки Надіслати посилання ще раз та Скасувати зміну.

Підтвердження зміни або її скасування зі старої адреси завершує всі сесії. Кожне посилання спрацьовує лише раз і діє 24 години. Адресу, яка вже належить іншому обліковому запису, відхиляють з тією самою відповіддю, що й під час реєстрації. EMAIL_SUPPORT_ADDRESS задає контакт, указаний у повідомленні на стару адресу; див. довідник конфігурації.

Денні ліміти

Обліковий запис може змінити адресу 3 рази на день і отримати 5 листів для підтвердження на день, сумарно для реєстрації, повторного надсилання і зміни адреси.

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

Адреси електронної пошти нечутливі до регістру: Ada@Company.com і ada@company.com — це той самий обліковий запис і для реєстрації, і для входу, запрошень, скидання пароля, зміни адреси та входу через Google. Адреси зберігаються в нижньому регістрі.

Під час реєстрації, запрошення учасників і зазначення email для рахунків Railhook відхиляє адресу з доменом, на який не може надходити пошта, як-от gmail.con, і пропонує адресу, яку, найімовірніше, мали на увазі.

Вхід через Google

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

• Якщо обліковому запису Google не відповідає жоден обліковий запис Railhook, його створюють одразу: адресу позначено як підтверджену, а користувач стає власником нової організації. Для облікового запису Google Workspace організацію називають за доменом (acme.com стає Acme), для особистого — Your name’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. Код працює лише в тому браузері, куди повернув Google: callback також встановлює короткочасне cookie railhook_signin_handoff, і без нього обмін коду буде відхилено. Посилання для входу, скопійоване в інший браузер, нічого не дасть.