crank/docs/admin-api.md

Admin API

1. Назначение документа

Этот документ фиксирует целевые HTTP-контракты административного API, через которое UI управляет workspace, operations, agents, machine access и observability.

Для потоковой модели детальные HTTP DTO вынесены отдельно в:

• docs/streaming-admin-api.md

2. Общие правила API

• все payload по умолчанию в JSON;
• import/export конфигурации используют YAML;
• все основные ресурсы являются workspace-scoped;
• версии operation и agent адресуются явно;
• published operation и published agent - ссылки на конкретные version;
• ошибки валидации возвращаются отдельно от transport errors.

Базовый префикс:

/api/admin

3. Основные ресурсы

• workspaces
• auth
• memberships
• invitations
• operations
• secrets
• auth-profiles
• agents
• agent-keys
• logs
• usage
• samples
• descriptors
• config import/export

4. Workspace-scoped routing

Канонический префикс для UI-driven сценариев:

/api/admin/workspaces/{workspace_id}

5. Группы endpoints

5.1. Workspaces and members

• GET /api/admin/workspaces
• POST /api/admin/workspaces
• GET /api/admin/workspaces/{workspace_id}
• PATCH /api/admin/workspaces/{workspace_id}
• DELETE /api/admin/workspaces/{workspace_id}
• GET /api/admin/workspaces/{workspace_id}/members
• PATCH /api/admin/workspaces/{workspace_id}/members/{user_id}
• DELETE /api/admin/workspaces/{workspace_id}/members/{user_id}
• GET /api/admin/workspaces/{workspace_id}/invitations
• POST /api/admin/workspaces/{workspace_id}/invitations
• DELETE /api/admin/workspaces/{workspace_id}/invitations/{invitation_id}
• GET /api/admin/workspaces/{workspace_id}/export

Контракт:

• POST /invitations возвращает metadata invitation и одноразовый invite_token;
• invite_token доступен только в create-response и не возвращается повторно в list endpoints;
• PATCH /members/{user_id} меняет роль участника;
• DELETE /members/{user_id} удаляет участника из workspace;
• GET /export возвращает JSON snapshot workspace lifecycle-данных;
• DELETE /workspaces/{workspace_id} разрешен только owner.

5.2. Auth and session

• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/session
• GET /api/auth/profile
• PATCH /api/auth/profile
• POST /api/auth/current-workspace
• POST /api/auth/password

Контракт:

• POST /login принимает email и password;
• при успешном логине backend выставляет HttpOnly session cookie;
• GET /session возвращает текущего пользователя, memberships и current_workspace_id;
• GET /profile возвращает текущего пользователя, memberships и current_workspace_id для settings UI;
• PATCH /profile обновляет display_name и email текущего пользователя;
• POST /current-workspace переключает текущий workspace внутри текущей authenticated session;
• POST /password меняет пароль текущего пользователя после проверки current_password;
• POST /logout инвалидирует текущую session.

5.3. Operations

• GET /api/admin/workspaces/{workspace_id}/operations
• POST /api/admin/workspaces/{workspace_id}/operations
• GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}
• PATCH /api/admin/workspaces/{workspace_id}/operations/{operation_id}
• DELETE /api/admin/workspaces/{workspace_id}/operations/{operation_id}
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions
• GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/versions/{version}
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/publish
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/archive
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/test-runs
• GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/export
• POST /api/admin/workspaces/{workspace_id}/operations/import

Контракт дополнительно включает:

• у операции задается обязательный security_level;
• допустимые значения: standard, elevated, strict;
• этот параметр определяет минимально допустимый режим машинного доступа при вызове через MCP.

5.4. Samples and descriptors

• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/input-json
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/samples/output-json
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/drafts/generate
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/proto
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/descriptor-set
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/wsdl
• POST /api/admin/workspaces/{workspace_id}/operations/{operation_id}/descriptors/xsd
• GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/grpc/services
• GET /api/admin/workspaces/{workspace_id}/operations/{operation_id}/soap/services

Контракт:

• POST /descriptors/wsdl принимает raw WSDL payload и сохраняет inspection metadata для SOAP;
• POST /descriptors/xsd принимает supporting XSD artifacts для SOAP operation;
• GET /soap/services возвращает нормализованный список service -> port -> operation из последнего WSDL текущего draft version.
• POST /operations/{operation_id}/test-runs остается единым test-run endpoint для unary, window, session и async_job execution modes;
• test-run response всегда возвращает mode, request_preview, response_preview, errors, а для streaming modes дополняется:
  • window с window_complete, truncated, has_more, cursor;
  • stream_session с session_id, status, expires_at, poll_after_ms, preview;
  • async_job с job_id, status, progress.

5.5. Upstream auth profiles

• GET /api/admin/workspaces/{workspace_id}/secrets

• POST /api/admin/workspaces/{workspace_id}/secrets

• GET /api/admin/workspaces/{workspace_id}/secrets/{secret_id}

• POST /api/admin/workspaces/{workspace_id}/secrets/{secret_id}/rotate

• DELETE /api/admin/workspaces/{workspace_id}/secrets/{secret_id}

• GET /api/admin/workspaces/{workspace_id}/auth-profiles

• POST /api/admin/workspaces/{workspace_id}/auth-profiles

• GET /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}

• PATCH /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}

• DELETE /api/admin/workspaces/{workspace_id}/auth-profiles/{auth_profile_id}

Контракт:

• POST /secrets принимает metadata и plaintext value, но create-response возвращает только metadata;
• GET /secrets и GET /secrets/{secret_id} возвращают только metadata, kind, status, current_version, created_at, updated_at, last_used_at при наличии;
• POST /secrets/{secret_id}/rotate создает новую secret version;
• DELETE /secrets/{secret_id} отклоняется, если secret все еще используется AuthProfile;
• AuthProfile.config хранит ссылки на secret_id, а не placeholder-строки ${secrets.*}.

5.6. Agents

• GET /api/admin/workspaces/{workspace_id}/agents
• POST /api/admin/workspaces/{workspace_id}/agents
• GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}
• PATCH /api/admin/workspaces/{workspace_id}/agents/{agent_id}
• DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions
• GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/publish
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/unpublish
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/archive
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings
• DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/bindings/{operation_id}
• GET /api/admin/workspaces/{workspace_id}/agents/{agent_id}/keys
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/keys
• POST /api/admin/workspaces/{workspace_id}/agents/{agent_id}/keys/{key_id}/revoke
• DELETE /api/admin/workspaces/{workspace_id}/agents/{agent_id}/keys/{key_id}

Контракт:

• POST /agents/{agent_id}/keys возвращает metadata ключа и одноразовый secret;
• полное значение ключа доступно только в create-response;
• list endpoints возвращают только metadata, prefix, status, scopes, expires_at и last_used_at;
• ключ агента принадлежит одному agent и не должен использоваться как основной рабочий токен вызова в целевой защищенной схеме;
• ключ агента используется для получения короткоживущего токена доступа к MCP endpoint.

5.7. Token issuance

Для расширенных редакций платформы:

• POST /mcp-auth/v1/token
• POST /mcp-auth/v1/token/one-time

Контракт:

• POST /mcp-auth/v1/token выдает короткоживущий токен доступа для операций уровня elevated;
• POST /mcp-auth/v1/token/one-time выдает одноразовый токен для операций уровня strict;
• открытая редакция может не использовать эти конечные точки и работать только со статическим ключом агента;
• детальная схема уровней и режимов доступа зафиксирована в docs/agent-auth-model.md.

5.8. Observability

• GET /api/admin/workspaces/{workspace_id}/logs
• GET /api/admin/workspaces/{workspace_id}/logs/{log_id}
• GET /api/admin/workspaces/{workspace_id}/usage
• GET /api/admin/workspaces/{workspace_id}/usage/operations/{operation_id}
• GET /api/admin/workspaces/{workspace_id}/usage/agents/{agent_id}

Контракт:

• GET /logs поддерживает level, search, source, operation_id, agent_id, period, limit;
• period использует UI-friendly значения 30m, 1h, 6h, 24h, 7d, 30d, 90d, this_month;
• source различает admin_test_run и agent_tool_call;
• GET /usage возвращает summary, timeline, operations, agents одним ответом;
• detail endpoints по operation и agent возвращают rollup для выбранного периода.

6. Page-to-endpoint mapping

Operations catalog

Нужны:

• список операций;
• удаление операции;
• edit/open operation;
• publish/archive;
• usage summary для карточек и фильтров.

Wizard

Нужны:

• create/update version;
• test run;
• samples;
• draft generation;
• gRPC descriptor upload и discovery.
• upstream auth selector;
• quick-create secret / auth profile modal.
• execution mode selector;
• streaming config blocks;
• stream test-runs;
• tool family preview.

Детальные DTO и response shapes для экранов Operations и Wizard зафиксированы отдельно в:

• docs/operations-workspace-contracts.md

Agents

Нужны:

• CRUD агентов;
• bindings к operations;
• publish agent;
• выдача MCP endpoint metadata.

API Keys

Нужны:

• list/create/revoke/delete agent keys;
• one-time reveal значения ключа при создании;
• для расширенных редакций — выдача короткоживущих и одноразовых токенов.

Secrets

Нужны:

• list/create/rotate/delete upstream secrets;
• metadata-only retrieval после создания;
• связь с auth profiles;
• usage references, чтобы оператор видел, где секрет используется.

Logs

Нужны:

• list logs с фильтрами;
• log detail;
• polling или live refresh strategy.

Usage

Нужны:

• агрегаты по периодам;
• breakdown по operation;
• breakdown по agent;
• CSV export.

Текущая реализация:

• summary и breakdown считаются по invocation_logs;
• materialized usage_rollups остаются совместимым storage-слоем для дальнейшей оптимизации, но не являются единственным source of truth в MVP.

7. Принцип совместимости

Если UI расходится с текущим backend, приоритет отдается целевой продуктовой модели, но конфликт должен быть явно разобран в docs/as-is-to-be.md до начала реализации.