Получение доступа MCP-агентом

Параметры запроса

• owner_email (string, обязательно) — e-mail владельца или уполномоченного администратора проекта, до 255 символов;
• agent_name (string, обязательно) — понятное имя агента, от 1 до 255 символов;
• agent_login (string, необязательно) — уникальный технический login, от 3 до 255 символов;
• permissions (string[], необязательно) — до 100 существующих permissions с guard_name = user;
• purpose (string, необязательно) — назначение агента, до 5000 символов.

project_id и role_id клиент не передаёт.

Пример запроса

{
	"owner_email": "owner@example.com",
	"agent_name": "MCP Order Assistant",
	"agent_login": "mcp-order-assistant",
	"permissions": [
		"view-orders",
		"view-counterparties"
	],
	"purpose": "Читать заказы и готовить сводки"
}

Ответ

{
	"message": "Если такой администратор есть, мы отправили запрос.",
	"request": {
		"public_id": "3f48862d-516d-4c7b-b486-9b7bb205f920",
		"request_token": "<request_token>",
		"expires_at": "2026-08-16T16:30:00+00:00"
	}
}

Сохраните public_id и request_token сразу. request_token показывается клиенту в этом ответе и используется для status и consume.

Ответ намеренно нейтрален: он не раскрывает, существует ли owner_email и имеет ли пользователь право подтверждать запрос.

Backend ограничивает отправку approval-письма одному владельцу: не чаще одного письма за 10 минут. Новый access request при этом всё равно может получить 201, но письмо для него не будет отправлено. Не создавайте запросы повторно сразу после успешного ответа.

Параметры пути

• publicId (string, обязательно) — публичный UUID запроса из ответа создания.

Пример запроса

GET /api/agent-access-requests/3f48862d-516d-4c7b-b486-9b7bb205f920/review
Accept: text/html

Ответ

Backend возвращает HTML-страницу подтверждения. Ссылка из письма содержит секрет во fragment:

https://api.gigma.ru/api/agent-access-requests/{publicId}/review#approval_token=<secret>

Fragment не отправляется серверу в URL. Страница читает approval_token, удаляет его из адресной строки и передаёт дальше только в JSON body.

Параметры запроса

• approval_token (string, обязательно) — секрет из fragment ссылки подтверждения.

approval_token запрещено передавать в query string. Backend вернёт 422.

Пример запроса

{
	"approval_token": "<approval_token>"
}

Ответ

{
	"status": "pending",
	"request": {
		"public_id": "3f48862d-516d-4c7b-b486-9b7bb205f920",
		"agent_name": "MCP Order Assistant",
		"agent_login": "mcp-order-assistant",
		"role": {
			"id": 14,
			"name": "employee"
		},
		"requested_permissions": [
			"view-orders",
			"view-counterparties"
		],
		"approved_permissions": null,
		"purpose": "Читать заказы и готовить сводки",
		"expires_at": "2026-08-16T16:30:00+00:00"
	}
}

Параметры запроса

• approval_token (string, обязательно) — секрет подтверждения;
• permissions (string[], необязательно) — итоговое подмножество первоначально запрошенных permissions.

Если permissions не переданы, backend пытается одобрить весь requested-набор. Недоступные права не отбрасываются автоматически: запрос вернёт 422.

Во время approve backend выбирает роль проекта:

1. employee;
2. если её нет — legacy employer.

Если подходящей роли нет или подтверждающий пользователь не может её назначить, backend возвращает 422.

Пример запроса

{
	"approval_token": "<approval_token>",
	"permissions": [
		"view-orders"
	]
}

Ответ

{
	"status": "approved",
	"message": "Доступ одобрен. Агент может забрать токен."
}

Параметры запроса

• approval_token (string, обязательно) — секрет подтверждения.

Пример запроса

{
	"approval_token": "<approval_token>"
}

Ответ

{
	"status": "declined",
	"message": "Запрос доступа отклонён."
}

Параметры запроса

• request_token (string, обязательно) — секрет, полученный при создании access request.

request_token передаётся только в JSON body. Query string отклоняется с 422.

Пример запроса

{
	"request_token": "<request_token>"
}

Ответ

{
	"status": "approved",
	"expires_at": "2026-08-16T16:30:00+00:00",
	"server_time": "2026-08-16T16:05:12+00:00"
}

Polling:

• используйте интервал не меньше 3–5 секунд;
• применяйте backoff после 429;
• после approved переходите к consume;
• остановитесь после declined, expired или consumed.

Параметры запроса

• request_token (string, обязательно) — секрет, полученный при создании access request.

Вызывайте endpoint только после статуса approved.

Пример запроса

{
	"request_token": "<request_token>"
}

Ответ

Первый успешный ответ:

{
	"status": "consumed",
	"agent": {
		"id": 214,
		"name": "MCP Order Assistant",
		"login": "mcp-order-assistant"
	},
	"agent_token": {
		"id": 901,
		"name": "mcp-self-service",
		"value": "<agent_bearer>",
		"expires_at": "2027-08-16T16:05:20+00:00"
	}
}

agent_token.value показывается только в этом ответе. Сохраните его в secret storage до завершения операции.

Повторный consume не возвращает секрет:

{
	"status": "consumed",
	"already_consumed": true
}

Backend окончательно проверяет уникальность agent_login именно во время consume. Если login уже занят, ответ — 409; изменить login в одобренном request нельзя, нужен новый запрос.

Перед созданием агента backend повторно проверяет, что владелец всё ещё активен, имеет право подтверждать доступ и остаётся в том же проекте. После временного 403 или project conflict тот же одобренный request можно повторить после устранения причины, пока не истёк общий 30-минутный TTL.