API Keys

Аутентификация и fine-grained доступ для MCP и REST API с полным lifecycle management

Обзор

API ключи аутентифицируют MCP и REST API вызовы в FlowLink. Каждый ключ привязан к организации, наследует роль создателя и имеет настраиваемые scopes для fine-grained контроля доступа. Поддерживаются два типа: live (для production) и test (для development). Полный lifecycle: create → active → rotate → revoke → delete. Встроенный audit trail логирует все операции с ключами.

Scopes

Fine-grained resource:action

Все тарифы

Rotation

Grace period 24h без даунтайма

Все тарифы

Rate Limits

100 req/min, 60 MCP/min на ключ

Все тарифы

Audit Trail

Все операции с ключами логируются

Все тарифы

Архитектура

API ключи хранятся в зашифрованном виде (AES-256-GCM) в базе данных. При каждом API запросе ключ верифицируется: проверяется формат, статус (active), срок действия и scopes. Rate limiter применяет per-key лимиты. Все операции (create, rotate, revoke) логируются в audit trail.

# API key authentication flow

1. Получение:

Client → Authorization: Bearer flk_live_xxx → Gateway

# 2. Верификация:

Format check → status=active → not expired → scopes check

# 3. Rate limiting:

Per-key: 100 req/min, 60 MCP/min, 10 concurrent

# 4. Выполнение:

Forward to handler → audit log → response

Scopes

Формат: resource:action — как GitHub PAT. API ключ может иметь подмножество scopes создателя. Это позволяет создавать ключи с минимальными привилегиями для каждого MCP-клиента.

Scope	Описание
agents:read	Просмотр списка и статуса агентов
agents:write	Выполнение команд через агентов
agents:admin	Полное управление: регистрация, удаление, перезапуск
approvals:read	Просмотр очереди одобрений
approvals:write	Одобрение или отклонение команд
policy:read	Просмотр политик
policy:write	Создание и изменение политик
audit:read	Просмотр audit log
secrets:read	Чтение секретов (без раскрытия значения)
catalog:read	Просмотр Service Catalog
patterns:read	Просмотр паттернов
patterns:write	Применение паттернов к политикам
compliance:read	Просмотр compliance отчётов
system:read	Статус системы, метрики
system:write	Изменение конфигурации

Lifecycle

API ключ проходит через полный lifecycle от создания до удаления. Каждый этап логируется в audit trail.

Create

POST /api/v1/api-keys

Active

Используется для аутентификации

Rotate

POST /api/v1/api-keys/{id}/rotate

Rotating

Grace period: старый + новый

Revoked

POST /api/v1/api-keys/{id}/revoke

Deleted

DELETE /api/v1/api-keys/{id}

Типы ключей

🔑flk_live_

Live ключи — для production среды. Имеют полный доступ к API в рамках scopes. Подлежат ротации каждые 90 дней.

🧪flk_test_

Test ключи — для development и staging. Имеют ограниченный доступ. Не влияют на production данные. Безопасны для CI/CD.

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

Ротация создаёт новый ключ, а старый остаётся активным в течение grace period (default: 24 часа). Это позволяет обновить ключ в MCP-клиентах без прерывания работы. После grace period старый ключ автоматически деактивируется.

bash

1curl -X POST "https://api.flowlink.io/v1/api-keys/key_abc123/rotate" \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "grace_period_hours": 24
6  }'

json

1{
2  "id": "key_abc123",
3  "status": "rotating",
4  "old_key": "flk_live_old_xxxxxxxxxxxx",
5  "new_key": "flk_live_new_yyyyyyyyyyyy",
6  "grace_period_ends": "2026-01-16T15:00:00Z",
7  "message": "Update your clients with the new key. Old key will be invalidated after grace period."
8}

⚠️ Значение new_key отображается только один раз при ротации. Сохраните его немедленно.

Rate Limiting

Rate limits применяются per-key для предотвращения злоупотреблений. Превышение лимита возвращает HTTP 429 Too Many Requests.

Параметр	Live	Test
REST API (req/min)	100	30
MCP calls (req/min)	60	20
Max concurrent connections	10	3
Burst (краткосрочно)	120/10s	40/10s
Webhook deliveries (req/min)	50	10

Response headers для rate limiting: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp).

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

POST /api/v1/api-keys

bash

1curl -X POST "https://api.flowlink.io/v1/api-keys" \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "claude-code-prod",
6    "description": "Claude Code production client",
7    "scopes": ["agents:write", "approvals:read", "audit:read"],
8    "type": "live",
9    "expires_days": 90,
10    "metadata": {
11      "client": "claude-code",
12      "owner": "dev-team@company.com",
13      "environment": "production"
14    }
15  }'

json

1{
2  "id": "key_abc123",
3  "name": "claude-code-prod",
4  "description": "Claude Code production client",
5  "key": "flk_live_xxxxxxxxxxxxxxxxxxxx",
6  "type": "live",
7  "scopes": ["agents:write", "approvals:read", "audit:read"],
8  "metadata": {
9    "client": "claude-code",
10    "owner": "dev-team@company.com",
11    "environment": "production"
12  },
13  "created_at": "2026-01-15T14:00:00Z",
14  "expires_at": "2026-04-15T14:00:00Z",
15  "last_used": null,
16  "status": "active",
17  "rate_limits": {
18    "requests_per_minute": 100,
19    "mcp_calls_per_minute": 60,
20    "max_concurrent": 10
21  }
22}

⚠️ Значение key отображается только один раз при создании. Сохраните его немедленно. Повторный просмотр невозможен — API возвращает только префикс flk_live_xxx...masked.

Metadata ключей

Каждый ключ может содержать произвольные metadata для организации и аудита. Рекомендуемые поля:

client

MCP-клиент (claude-code, cursor, copilot)

owner

Ответственный (email)

environment

production / staging / development

project

Имя проекта или сервиса

ci_pipeline

ID CI/CD pipeline (для автоматических ключей)

Audit Trail для ключей

Все операции с API ключами логируются в audit trail. Это включает создание, ротацию, использование, revoke и удаление.

bash

1# Audit log для конкретного ключа
2curl -s "https://api.flowlink.io/v1/audit?resource_type=api_key&resource_id=key_abc123" \
3  -H "Authorization: Bearer $TOKEN" | jq

json

1{
2  "events": [
3    {
4      "event_id": "evt_key_created",
5      "event_type": "api_key_created",
6      "timestamp": "2026-01-15T14:00:00Z",
7      "actor": "admin@company.com",
8      "resource_id": "key_abc123",
9      "details": {
10        "name": "claude-code-prod",
11        "scopes": ["agents:write", "approvals:read", "audit:read"],
12        "type": "live"
13      }
14    },
15    {
16      "event_id": "evt_key_rotated",
17      "event_type": "api_key_rotated",
18      "timestamp": "2026-02-15T14:00:00Z",
19      "actor": "admin@company.com",
20      "resource_id": "key_abc123",
21      "details": {
22        "grace_period_hours": 24
23      }
24    }
25  ]
26}

API Reference

POST /api/v1/api-keysСоздать API ключ

GET /api/v1/api-keysСписок всех ключей организации

GET /api/v1/api-keys/{id}Получить ключ по ID

PATCH /api/v1/api-keys/{id}Обновить metadata или scopes

POST /api/v1/api-keys/{id}/rotateРотировать ключ

POST /api/v1/api-keys/{id}/revokeОтозвать ключ (немедленно)

DELETE /api/v1/api-keys/{id}Удалить ключ

GET /api/v1/api-keys/{id}/usageСтатистика использования

Статистика использования

bash

1curl -s "https://api.flowlink.io/v1/api-keys/key_abc123/usage?period=7d" \
2  -H "Authorization: Bearer $TOKEN" | jq

json

1{
2  "key_id": "key_abc123",
3  "name": "claude-code-prod",
4  "period": { "from": "2026-01-08", "to": "2026-01-15" },
5  "total_requests": 4521,
6  "total_mcp_calls": 2130,
7  "avg_requests_per_day": 645,
8  "rate_limit_hits": 3,
9  "last_used_at": "2026-01-15T14:28:30Z",
10  "top_agents": [
11    { "agent_id": "agent-prod-01", "requests": 3200 },
12    { "agent_id": "agent-prod-02", "requests": 1321 }
13  ],
14  "top_endpoints": [
15    { "endpoint": "POST /agents/{id}/command", "calls": 1890 },
16    { "endpoint": "GET /audit", "calls": 645 }
17  ]
18}

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

401 Unauthorized

Проверьте, что ключ передаётся в заголовке Authorization: Bearer flk_live_xxx. Убедитесь, что ключ не отозван и не истёк. Проверьте статус через GET /api-keys/{id}.

403 Forbidden

Ключ не имеет необходимых scopes для данного ресурса. Проверьте назначенные scopes через GET /api-keys/{id} и обновите через PATCH.

429 Too Many Requests

Превышен rate limit ключа. Используйте X-RateLimit-Reset header для определения времени сброса. Для повышения лимитов обратитесь к администратору.

Потерян ключ

Значение ключа отображается только при создании. Если ключ потерян — отзовите его (POST /api-keys/{id}/revoke) и создайте новый.

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

Один ключ на MCP-клиент

Создавайте отдельный ключ для каждого MCP-клиента (Claude Code, Cursor, Copilot) для гранулярного аудита и изоляции.

Используйте минимальные scopes

Не давайте policy:write если нужен только agents:write. Принцип наименьших привилегий.

Ротируйте ключи регулярно

Ротируйте каждые 90 дней или при компрометации. Используйте grace period для бесшовной ротации.

Используйте test-ключи для разработки

Test-ключи имеют сниженные лимиты и не влияют на production. Безопасны для CI/CD pipelines.

Храните ключи в secrets manager

Используйте HashiCorp Vault, AWS Secrets Manager или .env файлы. Никогда не коммитьте ключи в код.

Мониторьте использование

Проверяйте last_used и usage stats. Удалите неиспользуемые ключи. Алерт на аномальную активность.

← REST API Secrets →

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

SSO / SAML

Edit this page