Подключите ваше приложение к Notiondesk с помощью OAuth.

Notiondesk OAuth позволяет другим клиентам Notiondesk подключать ваше приложение к своему рабочему пространству без обмена ключом API. Клиент входит в Notiondesk, просматривает запросы вашего приложения и подтверждает их. Ваше приложение получает токен доступа к REST API Notiondesk, и клиент может отозвать его в любое время. В этой статье рассматривается регистрация вашего приложения, запуск процесса авторизации OAuth 2.0 с использованием PKCE, обновление токенов и обработка ошибок.

Когда следует использовать OAuth вместо ключа API?

Каждый маршрут API Notiondesk принимает оба типа учетных данных и отвечает на них одинаково: с одинаковыми областями действия, ответами и ошибками.

Что должно знать ваше приложение

Вместо того чтобы прописывать конечные точки в коде сервера авторизации, следует считывать их непосредственно из документа метаданных .

Запускайте свой OAuth-клиент на сервере. Клиенты, работающие через браузер, не поддерживаются: храните обмен токенов, сами токены и все вызовы API на своем бэкэнде.

Шаг 1: Зарегистрируйте свое приложение

Зарегистрируйтесь один раз с помощью динамической регистрации клиентов :

Ответ 201 Created содержит ваш client_id и, поскольку вы запросили client_secret_post, client_secret. Секрет отображается один раз: сохраните его вместе с другими секретами вашего сервера.

Благодаря "token_endpoint_auth_method": "none" ваше приложение становится публичным клиентом без секретных данных, а PKCE защищает обмен кодом.

Вместо регистрации вы можете использовать HTTPS-URL документа метаданных клиента в качестве параметра client_id. Notiondesk получает документ, когда клиент авторизует ваше приложение, и кэширует его на срок до пяти минут.

Правила перенаправления URI

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• Используйте https или http на хосте обратной связи: 127.0.0.1, localhost или [::1].

• Перенаправление через локальную точку (loopback) должно совпадать с любым портом. Любое другое перенаправление должно совпадать в точности.

• Подстановочные символы, фрагменты, учетные данные перед хостом (user@), обратные косые черты, символы, не относящиеся к ASCII, и хосты, закодированные в процентах, отклоняются.

• Хост, который клиент видит на экране согласия, берется из ваших URI перенаправления или вашего URL-адреса client_id. Регистрируйте только те хосты, которые принадлежат вам.

Шаг 2: Отправьте клиента по адресу Notiondesk

Создайте случайное значение code_verifier, затем вычислите code_challenge как хеш SHA-256 верификатора, закодированный в base64url ( PKCE ). Перенаправьте браузер клиента на:

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource является обязательным и должно точно соответствовать https://api.notiondesk.so: строчные буквы, без завершающей косой черты, без пути. Отсутствие или другое значение соответствует invalid_request.

• scope — это список, разделённый пробелами. Запрашивайте только те области видимости, которые использует ваше приложение.

• state защищает от подделки межсайтовых запросов. Проверьте это, когда клиент вернется.

Токен, выданный для REST API Notiondesk, работает только с REST API. Токен, выданный для Workspace MCP, отклоняется REST API, и наоборот.

Шаг 3: Клиент одобряет ваше приложение

Notiondesk отображает экран согласия. Клиент входит в систему и видит название и хост вашего приложения, свою рабочую область и области действия запроса, которые разрешены его ролью. Он одобряет или отклоняет весь запрос.

Доступные вашему приложению области действия зависят от роли клиента в рабочей области:

admin позволяет вашему приложению изменять фирменный стиль справочного центра, настраивать интеграции, скрипты которых загружаются в общедоступный справочный центр, и удалять перенаправления. Запрашивайте эту опцию только в том случае, если ваше приложение использует эти маршруты.

Клиент не может одобрить запрос в следующих случаях:

• Их роль не позволяет реализовать ни один из запрошенных вами вариантов;

• В их рабочем пространстве отсутствует доступ к API. На экране согласия отображается сообщение «Тарифный план рабочего пространства не включает доступ к API». Для доступа к API требуется тарифный план «Предприятие».

После подтверждения браузер возвращается к вашему redirect_uri с code, вашим state и iss, идентификатором сервера авторизации Notiondesk. Если клиент отклоняет запрос, перенаправление вместо этого передает error=access_denied.

Шаг 4: Обменяйте код на токены.

Код действителен в течение 60 секунд и срабатывает один раз:

Для общедоступного клиента следует исключить client_secret. Ответ:

scope отображает предоставленные клиентом права доступа, которых может быть меньше, чем вы запрашивали. Сохраните оба токена на своем сервере.

Шаг 5: Вызовите API Notiondesk

Отправьте токен доступа в виде токена носителя, точно так же, как и ключ API:

Область действия токена ограничена текущей ролью утверждающего клиента: клиент, изменивший роль на «Просмотрщик», покидает ваше приложение только с ролью read, а маршрут, которому требуется отсутствующая область действия, отвечает ошибкой 403 insufficient_scope.

Ограничения скорости запросов и значения Idempotency-Key относятся к гранту. Каждое одобрение представляет собой новый грант со своими собственными бюджетами и ключами, а обновление токена сохраняет и то, и другое.

Шаг 6: Обновите токен доступа.

Срок действия токена доступа составляет один час. До истечения срока его действия обменяйте токен обновления на новую пару:

Каждое обновление возвращает новый токен обновления, действительный в течение 30 дней, и аннулирует отправленный вами токен. Сохраните новый токен обновления перед использованием нового токена доступа.

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

curl "https://api.notiondesk.so/sites" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "nd-version: 2026-10-16"

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

Никогда не используйте повторно токен обновления. Отправка уже использованного токена аннулирует все права доступа, включая сам токен, поскольку повторное использование означает копирование токена. В этом случае клиенту потребуется повторно авторизовать ваше приложение.

Как клиенты отзывают ваше приложение

Владельцы и администраторы рабочих пространств видят все приложения, имеющие доступ к их рабочему пространству, в разделе «Настройки» > «Разработчики» > «Подключенные приложения» . Приложения, использующие REST API, отображаются в столбце «Доступ» , где указывается само приложение, авторизованный пользователь, его области действия и последняя активность. Функция «Отзыв» немедленно прекращает предоставление доступа: токен доступа и токен обновления перестают работать при следующем запросе.

Грант также прекращает свое действие сам по себе:

• после 30 дней без обновления;

• когда его токен обновления используется повторно.

Если у утверждающего клиента отсутствует необходимая для маршрута роль, или план рабочего пространства не имеет доступа к API, запросы отклоняются. Они снова запускаются, если роль или план возвращаются до окончания срока действия разрешения.

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

Конечные точки авторизации и токена обрабатывают стандартные ошибки OAuth, а не ошибки API Notiondesk:

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

Конечная точка авторизации сама отображает эти ошибки и никогда не перенаправляет недействительный запрос на ваш redirect_uri. Отказанное согласие попадает в ваше приложение только в виде перенаправления error=access_denied.

При обращении к самому API выводится сообщение об ошибке API Notiondesk . Если токен доступа просрочен или отозван, выводится сообщение 401 authentication_error с текстом "Недействительный или отсутствующий ключ API", то же самое сообщение получает и неработающий ключ API.

Часто задаваемые вопросы

Что дальше?

• Начните работу с REST API Notiondesk

• Аутентификация с помощью API Notiondesk осуществляется с использованием ключей API.

• Отключите или отзовите доступ к панели управления Workspace MCP.