Аутентификация и авторизация

JWT, API Keys, OAuth и SAML SSO — все способы доступа к FlowLink API

Обзор методов аутентификации

FlowLink поддерживает несколько методов аутентификации для разных сценариев использования. Токены хранятся в httpOnly cookies для веб-интерфейса и передаются через заголовки для API-доступа.

JWT

Dashboard, REST API

Все тарифы

API Key

MCP, интеграции

Все тарифы

OAuth 2.0

GitHub, Telegram

Все тарифы

SAML SSO

Enterprise

JWT аутентификация

Основной метод для веб-интерфейса и REST API. JWT-токены устанавливаются в httpOnly cookies сервером, JavaScript не имеет к ним доступа.

Жизненный цикл токена

# 1. Регистрация / Вход

POST /api/auth/login

# → Сервер устанавливает httpOnly cookies:

Set-Cookie: fl_access_token=eyJ...; HttpOnly; Secure; SameSite=Lax; Max-Age=3600

Set-Cookie: fl_refresh_token=...; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000

# 2. Использование — cookies отправляются автоматически

GET /api/agents

Cookie: fl_access_token=eyJ... # браузер автоматически

# 3. Refresh — автоматическое обновление access token

POST /api/auth/refresh

Регистрация нового пользователя

bash

1curl -X POST https://flowlink.flow-masters.ru/api/auth/signup \
2  -H "Content-Type: application/json" \
3  -d '{
4    "email": "user@example.com",
5    "password": "secure_password",
6    "name": "User Name"
7  }'
8
9# Ответ
10{
11  "user": {
12    "id": "acc_xxxx",
13    "email": "user@example.com",
14    "name": "User Name",
15    "org_id": "org_xxxx"
16  },
17  "access_token": "eyJhbGciOiJIUzI1NiIs...",
18  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
19}

Вход по email и паролю

bash

1curl -X POST https://flowlink.flow-masters.ru/api/auth/login \
2  -H "Content-Type: application/json" \
3  -d '{"email": "user@example.com", "password": "secure_password"}'
4
5# Ответ — токены + пользователь
6{
7  "user": {
8    "id": "acc_xxxx",
9    "email": "user@example.com",
10    "name": "User Name",
11    "org_id": "org_xxxx",
12    "org_role": "admin",
13    "is_admin": false,
14    "oauth_provider": null
15  },
16  "access_token": "eyJhbGciOiJIUzI1NiIs...",
17  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
18}

Обновление токена

bash

1curl -X POST https://flowlink.flow-masters.ru/api/auth/refresh \
2  -H "Content-Type: application/json" \
3  -b "fl_refresh_token=dGhpcyBpcyBhIHJlZnJlc2g..."
4
5# Ответ
6{
7  "access_token": "eyJhbGciOiJIUzI1NiIs...",
8  "refresh_token": "bmV3IHJlZnJlc2ggdG9rZW4..."
9}

API Key аутентификация

API-ключи предназначены для серверного доступа: MCP-серверы, CI/CD пайплайны, внешние интеграции. Ключи привязаны к организации и имеют настраиваемые права.

Использование API-ключа

bash

1# Способ 1: Заголовок Authorization (рекомендуется)
2curl https://flowlink.flow-masters.ru/api/v1/agents \
3  -H "Authorization: Bearer flk_live_abc123def456"
4
5# Способ 2: Заголовок x-api-key
6curl https://flowlink.flow-masters.ru/api/v1/agents \
7  -H "x-api-key: flk_live_abc123def456"
8
9# Способ 3: Query-параметр (для WebSocket)
10wss://flowlink.flow-masters.ru/relay?api_key=flk_live_abc123def456

Создание API-ключа

bash

1curl -X POST https://flowlink.flow-masters.ru/api/v1/api-keys \
2  -H "Authorization: Bearer eyJ..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "MCP Server",
6    "permissions": ["agents:read", "shield:read", "approvals:write"],
7    "expires_at": "2026-06-15T00:00:00Z"
8  }'
9
10# Ответ — секрет показан только один раз
11{
12  "id": "key_xxxx",
13  "name": "MCP Server",
14  "key": "flk_live_abc123def456",
15  "prefix": "flk_live_",
16  "permissions": ["agents:read", "shield:read", "approvals:write"],
17  "created_at": "2026-05-15T10:00:00Z",
18  "expires_at": "2026-06-15T00:00:00Z",
19  "last_used_at": null
20}

Префиксы ключей

flk_live_

Продакшн-ключи

flk_test_

Тестовые ключи

flk_sched_

Ключи для scheduled-задач

OAuth 2.0

FlowLink поддерживает OAuth 2.0 для входа через внешних провайдеров. Поддерживаемые провайдеры определяются конфигурацией сервера.

bash

1# Получение списка провайдеров
2curl https://flowlink.flow-masters.ru/api/auth/providers
3
4# Ответ
5{
6  "providers": ["email", "github", "telegram"]
7}
8
9# Получение OAuth URL
10curl "https://flowlink.flow-masters.ru/api/auth/oauth-url?provider=github&redirect=https://flowlink.flow-masters.ru/auth/callback"
11
12# Ответ
13{
14  "url": "https://github.com/login/oauth/authorize?client_id=xxx&redirect_uri=..."
15}
16
17# После OAuth callback — сервер устанавливает cookies автоматически
18# Клиент вызывает /api/auth/me для получения профиля
19curl https://flowlink.flow-masters.ru/api/auth/me -b "fl_access_token=eyJ..."
20
21{
22  "user": {
23    "id": "acc_xxxx",
24    "email": "user@example.com",
25    "name": "GitHub User",
26    "oauth_provider": "github",
27    "org_id": "org_xxxx"
28  }
29}

SAML SSO

Enterprise SSO через SAML 2.0. Поддерживает Keycloak, AD FS, Azure AD, Okta и других совместимых провайдеров. Доступен на тарифе Enterprise.

Инициация входа

GET /auth/saml/login?relay_state=/dashboard

Assertion Consumer Service

POST /auth/saml/acs

SP Metadata

GET /auth/saml/metadata

Single Logout

GET /auth/saml/logout

Настройка SAML в Keycloak

bash

1# 1. Скачайте SP Metadata из FlowLink
2curl -o flowlink-sp-metadata.xml https://flowlink.flow-masters.ru/auth/saml/metadata
3
4# 2. Импортируйте в Keycloak: Realm → Clients → Import
5
6# 3. Настройте ACS URL в Keycloak:
7#     Client ID: flowlink
8#     Client Protocol: saml
9#     Assertion Consumer Service URL:
10#    https://flowlink.flow-masters.ru/auth/saml/acs

Права доступа и scope

API-ключи и JWT-токены поддерживают гранулярные права доступа. Каждое право ограничивает доступ к определённым endpoints.

Право	Описание
agents:read	Чтение списка агентов и статуса
agents:write	Регистрация и удаление агентов
shield:read	Просмотр алертов Shield
shield:write	Управление политиками Shield
approvals:read	Просмотр запросов на согласование
approvals:write	Согласование/отклонение команд
policies:read	Чтение политик
policies:write	Создание и редактирование политик
patterns:read	Просмотр паттернов
patterns:write	Создание и удаление паттернов
api-keys:write	Управление API-ключами
audit:read	Просмотр аудита

Публичные и защищённые endpoints

Публичные (без авторизации)

GET /health
POST /api/auth/signup
POST /api/auth/login
GET /api/auth/providers
POST /api/playground/scan
MCP: initialize, tools/list

Защищённые (требуют авторизации)

MCP: tools/call
GET /api/agents
API Keys CRUD
Policies CRUD
Approvals API
Patterns API
Audit Log

Ошибки авторизации

json

1// Невалидный токен
2{
3  "error": "unauthorized",
4  "message": "Invalid or expired access token"
5}
6// Status: 401
7
8// Недостаточно прав
9{
10  "error": "forbidden",
11  "message": "Insufficient permissions: requires agents:write"
12}
13// Status: 403
14
15// API-ключ не найден
16{
17  "error": "invalid_api_key",
18  "message": "API key not found or expired"
19}
20// Status: 401
21
22// Фича недоступна на тарифе
23{
24  "error": "feature_not_available",
25  "feature": "forensics",
26  "required_plan": "team",
27  "upgrade_url": "/pricing?upgrade=team"
28}
29// Status: 403

Лучшие практики

Используйте httpOnly cookies

JWT-токены в httpOnly cookies защищены от XSS. Избегайте хранения токенов в localStorage.

Ключи с минимальными правами

API-ключи должны иметь только те права, которые необходимы для конкретной задачи.

Ротация ключей

Регулярно обновляйте API-ключи. Устанавливайте срок действия для Production-ключей.

Не логируйте токены

Исключите Authorization и x-api-key заголовки из логов. Используйте маскирование.

Валидируйте audience/issuer

При настройке SAML всегда проверяйте audience restriction и issuer URL.

Устранение неполадок

401 после успешного входа

Убедитесь что браузер отправляет cookies (credentials: include). Проверьте настройки SameSite — CORS-запросы из другого домена не отправят cookies без SameSite=None; Secure.

Токен истекает слишком быстро

Access token живёт 1 час. Используйте refresh token для автоматического обновления. Если refresh token также истёк — потребуется повторный вход.

SAML login не работает

Проверьте SP Metadata — entity ID и ACS URL должны совпадать с конфигурацией IdP. Убедитесь что часы серверов синхронизированы (NTP).

← REST API API Keys →

REST API

API Ключи

Edit this page