---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.0
description: >-
  Как выбрать стенд, получить токен, настроить авторизацию и проверить учётную
  запись и роль перед вызовом API.
vcsPath: motorway/magacg/support/docs/src/ru-x-ai/guides/api-access.md
updatedAt: '2026-11-12T12:16:53.000Z'
alternate:
  - href: https://yamagistrali.ru/docs/ru-x-ai/guides/api-access.md
    type: text/markdown
    title: Markdown version
  - href: https://yamagistrali.ru/docs/ru-x-ai/llms.txt
    rel: describedby
---

# Доступ к API

Перед первым защищённым вызовом определите стенд, учётную запись и организацию, от имени которой нужно выполнить задачу.

## Выбрать стенд

| Стенд | Базовый URL | Когда использовать |
| --- | --- | --- |
| Тестовый | `https://partner-test-yamagistrali.ru` | Разработка и проверка интеграции по умолчанию |
| Рабочий | `https://yamagistrali.ru` | Работа с данными пользователя после явного выбора стенда |

Проверяйте токен, права и идентификаторы объектов на выбранном стенде. Перед операцией записи на рабочем стенде согласуйте с пользователем действие и объект.

## Получить токен {#get-token}

Пользователь открывает ссылку Яндекс OAuth для выбранного стенда и входит под нужным Яндекс ID. После входа откроется страница с токеном.

- [Получить токен тестового стенда](https://oauth.yandex.ru/authorize?response_type=token&client_id=456087b4e2554a3ead284d8115835732&redirect_uri=https://oauth.yandex.ru/verification_code)
- [Получить токен рабочего стенда](https://oauth.yandex.ru/authorize?response_type=token&client_id=d806112517c04057b82c1e776efb4648&redirect_uri=https://oauth.yandex.ru/verification_code)

Эти ссылки приведены в [инструкции по получению токена для разработчиков](https://yamagistrali.ru/docs/ru/pages/api/access/access.md#avtomaticheskij-sposob-rekomenduetsya-dlya-razrabotki). Для ручной проверки вызовов в браузере используйте [авторизацию через OpenAPI](https://yamagistrali.ru/docs/ru/pages/api/access/access.md#avtorizaciya-cherez-openapi).

## Настроить авторизацию

1. Проверьте, есть ли у [клиента](https://yamagistrali.ru/docs/ru-x-ai/guides/generate-client.md) настроенный источник токена для выбранного стенда. Если токена ещё нет, направьте пользователя к [получению токена](https://yamagistrali.ru/docs/ru-x-ai/guides/api-access.md#get-token).
2. Если способ передачи токена клиенту ещё не настроен, [согласуйте его с пользователем](https://yamagistrali.ru/docs/ru-x-ai/guides/secrets.md). Достаточно узнать имя секрета и способ его подключения. Значение токена пользователь вводит через интерфейс хранилища или среды запуска.
3. Клиент добавляет заголовок `Authorization: Bearer <токен>` к защищённым запросам на выбранный стенд. Для общедоступного метода используйте вызов без токена, если это указано в карточке.

## Проверить учётную запись и роль {#verify-access}

С одной учётной записью можно работать от имени нескольких организаций. У пользователя могут быть профили заказчика в одних организациях и профили исполнителя в других. Один профиль может иметь оба признака роли.

Методы в первых двух шагах возвращают JSON. Если клиент передал байты, [разберите ответ](https://yamagistrali.ru/docs/ru-x-ai/concepts/agent-workflow.md#read-response) перед чтением `data`.

1. Вызовите [метод получения идентификаторов текущего пользователя](https://yamagistrali.ru/docs/ru-x-ai/methods/user.get-ya-id.v0.md) без тела и параметров. Ответ `200 OK` подтверждает аутентификацию. Если клиенту известны ожидаемые идентификаторы учётной записи, сравните их с ответом в клиенте. При несовпадении остановитесь.
2. Вызовите [метод получения профилей сотрудников](https://yamagistrali.ru/docs/ru-x-ai/methods/users.user-employees.get-list.v0.md) на том же стенде и с той же учётной записью. В `data.empls` найдите профили, у которых `isOn: true` и установлен признак нужной роли. Заказчику (`forwarder`) соответствует `isForwarder: true`, исполнителю (`executor`) — `isExecutor: true`.
3. Если пользователь указал название организации, сопоставьте его с `orgName` подходящих профилей в клиенте. Если указан идентификатор, сверьте его с `organizationID`. Если выбор неоднозначен, уточните организацию у пользователя. Для дальнейших вызовов используйте `organizationID` выбранного профиля. Порядок профилей в ответе не задаёт организацию по умолчанию.
4. Сообщите, прошла ли аутентификация и найден ли активный профиль нужной роли с учётом выбранной организации. Если подходящего профиля нет, остановитесь и предложите проверить в интерфейсе сервиса Яндекс Магистрали доступ учётной записи к нужной организации и её роль. Права на бизнес-операцию проверяйте отдельно по условиям доступа в её карточке.

## Если доступ отклонён

- При `401` остановите сценарий. Проверьте настройку заголовка авторизации, срок действия токена и соответствие стенду.
- При `403` остановите сценарий. Проверьте доступ учётной записи к выбранному стенду, организации и операции.

Сообщите пользователю стенд, метод и HTTP-статус. Для диагностики достаточно этих сведений и подтверждённых условий доступа. Токен, заголовки и полные ответы держите в клиенте. При проверке профилей соблюдайте [правила работы с персональными и чувствительными данными](https://yamagistrali.ru/docs/ru-x-ai/concepts/sensitive-data.md).