> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Настройка аутентификации Didit через API

> Настраивайте в Didit методы входа, параметры, брендинг и защиту из своего кода: с грантом, одобренным владельцем, или API-ключом аутентификации.

Didit Authentication позволяет включать методы входа и получать настройки вашего приложения через API. Используйте грант, одобренный владельцем, или именованный API-ключ с областью `authentication`.

> [!WARNING]
>
> Продукт Authentication является новым. Сначала настройте метод в песочнице приложения, а затем в продакшн-приложении.

Каждый вызов ниже отправляется в API управления Authentication вашего приложения. `MANAGEMENT_BASE` имеет следующий вид:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

Те же маршруты описаны в `openapi-authentication.json` под тегом `Setup`; серверные SDK заново генерируются на основе этого файла.

## Какие учётные данные использовать

Подходят любые из трёх видов учётных данных, и каждый вид ограничен тем, что его владелец одобрил.

| Учётные данные | Передаются как | Что они могут |
| - | - | - |
| Именованный API-ключ с областью `authentication` | `x-api-key: <key>` | Настраивает собственное приложение и читает его настройки. Ключ с `read` может только читать настройки; `write` позволяет и читать, и изменять их. |
| Грант, одобренный владельцем, с `didit:management` | `Authorization: Bearer <access_token>` | Настраивает приложения организаций, которые были одобрены при предоставлении согласия, в рамках роли пользователя. |
| Сессия консоли | `Authorization: Bearer <console session token>` | Читает или изменяет настройки в соответствии с членством пользователя в организации и его ролью. Просмотр данных конечных пользователей также требует сессии консоли и соответствующих разрешений. |

Эти учётные данные отклоняются с кодом `403` на каждом маршруте настройки, независимо от того, что запрашивает запрос:

* **Основной секрет** приложения.
* Токен, полученный из `POST /programmatic/login`, который выпускается для приложения, а не для консоли.
* Ключ **без** области `authentication`, включая ключ, созданный со всеми ресурсами на максимальном уровне: такие ключи отображаются как полный доступ, поле `scopes` остаётся пустым, и на этих маршрутах они не принимаются.
* Ключ **другого приложения**, грант, ограниченный областью `didit:verification`, а также грант, одобренный для другой организации.

Запрос без каких-либо учётных данных возвращает `401`. Грант или ключ дополнительно сохраняют собственные ограничения: у гранта это его области, организации и роль пользователя, у ключа это его области, список разрешённых IP-адресов и срок действия.

## Одобрение доступа

### С именованным API-ключом

Откройте **Developers -> API keys** в [Business Console](https://business.didit.me) и создайте ключ для приложения, которое вы настраиваете. Назначьте ему ресурс `authentication` с правом **read** или **write**. Право read дает доступ ко всем вызовам, которые читают настройки (`GET`). Право write дает доступ ко всем вызовам, которые их меняют (`POST`, `PUT`, `PATCH`, `DELETE`), и также позволяет читать настройки. Сведения о сроке действия, списках разрешенных IP-адресов и ротации см. в разделе [API-ключи](https://docs.didit.me/ru/console/api-keys.md). Ключ принадлежит одному приложению и работает только с ним.

### Через подключение MCP

Агент, подключенный к MCP-серверу Didit, использует доступ, который его владелец одобрил на экране согласия, с областью `didit:management`. См. [Аутентификация MCP](https://docs.didit.me/ru/integration/mcp/authentication.md#вход-через-didit).

### Для владельца без пароля

Грант кода устройства ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) позволяет владельцу, который входит через Google, ключ доступа или код из письма, одобрить тот же доступ из любого браузера, без ввода пароля. См. [вход без браузера](https://docs.didit.me/ru/integration/mcp/authentication.md#вход-без-браузера-код-устройства).

## Включение кода по электронной почте

`PUT methods/{name}/` принимает только `enabled`, и больше ничего, если для метода не нужны учетные данные.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

В ответе возвращается метод в текущем состоянии:

```json theme={null}
{"name": "code", "enabled": true}
```

Когда вы читаете конфигурацию, запись для кода по электронной почте содержит `credential_source: null`. Методы, которые всегда включены, отключить нельзя: такой запрос возвращает `{"enabled": "always_on"}`.

## Включение Google

Способ входа через социальную сеть принимает учетные данные вашего собственного OAuth-приложения или тестового приложения Didit для приложения в песочнице.

### С собственным приложением Google

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Зарегистрируйте у своего провайдера `callback_uri`, который возвращается в ответе. Секрет доступен только для записи: ни один ответ его не возвращает, а `client_id` - единственная часть, которую можно прочитать обратно. Если включить способ входа без учетных данных, когда они не были сохранены ранее, сервер ответит `{"credentials": "required"}`.

### С тестовым приложением Didit (`didit_test`)

**Приложение в песочнице** может использовать социальные приложения самой Didit вместо ваших. Этого достаточно, чтобы завершить настройку и проверить, что она работает:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` поддерживает **Google, Microsoft, Apple и GitHub**, только для приложений в песочнице:

| Ответ | Когда |
| - | - |
| `{"credential_source": "sandbox_only"}` | Приложение работает в продакшне. Тестовые приложения не обслуживают реальные входы. |
| `{"credential_source": "unavailable"}` | В этом развертывании нет тестового приложения для данного провайдера, поэтому способ входа остается выключенным. |
| `200` с `configured: true` | Тестовое приложение обслуживает этот способ, и размещённая страница входа его предлагает. |

`GET` для конфигурации указывает в `didit_test_credentials`, каких провайдеров тестовое приложение может обслуживать для этого приложения. Для всех четырех значение `false` в продакшн-приложении.

## Чтение настроек

`GET` на `MANAGEMENT_BASE` возвращает настройки: каждый метод с `enabled` и `credential_source`, а также URL-адреса обратного вызова, правила сессии и политику регистрации.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Отключённые методы тоже включены в ответ, поэтому один `GET` показывает, что включено, а что нет. Значение `enabled` на верхнем уровне равно `false`, если аутентификация отключена для приложения. Любое изменение настроек с грантом управления или именованным ключом в этом случае возвращает `409` с `{"detail": "product_disabled"}`, и ничего не записывается. Ни один вызов для изменения настроек не включает аутентификацию: её включает пользователь в консоли для приложения, после чего ваши вызовы начинают работать.

## Остальная настройка

| Маршрут относительно `MANAGEMENT_BASE` | Методы | Что хранится |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Доступ агентов, организации, политика MFA, роль участника по умолчанию, отключённые события webhook |
| `onboarding/` | `GET`, `PATCH` | Какие шаги настройки выполнены и входят ли пользователи через размещённую страницу или ваши собственные экраны |
| `branding/` | `GET`, `PATCH` | Тексты размещённых страниц и юридические ссылки (логотип и цвета задаются в Customization) |
| `protection/` | `GET`, `PATCH` | Политики защиты от ботов ([защита от ботов](https://docs.didit.me/ru/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | Уровень верификации при регистрации, правила повышения уровня проверки и клеймы токена |
| `emails/`, `emails/{key}/` | `GET` | Письма для входа, которые отправляет это приложение, и отрисованный предпросмотр |
| `domain/` | `GET`, `PUT`, `DELETE` | Размещённый источник и пользовательский домен для входа |
| `domain/verify/`, `domain/activate/` | `POST` | Проверка DNS и сертификата домена, затем назначение его каноническим источником |
| `native-apps/` | `GET`, `PUT` | Приложения для iOS и Android, которые используют ключи доступа этого приложения |

Ключ или грант получает доступ только к настройке и её счётчикам, но никогда не к данным конечных пользователей: `users/`, `sessions/`, `sign-ins/`, `overview/`, клиентские организации, роли, импорты, сессии агентов и тестовые письма по-прежнему требуют сессии в консоли.

Настройка `agent_humans_only` действует на всё приложение. Изменить её может только владелец или администратор организации. Именованный ключ получит `403 owner_or_admin_required`. Включение этой настройки также требует зарегистрированного ключа доступа (`passkey_required`).

## Ошибки

| Ответ | Значение |
| - | - |
| `401` | Учётные данные не переданы. |
| `403` | Учётные данные, которые не могут настраивать это приложение, либо одно из его собственных ограничений: `ip_not_allowed`, ключ с истёкшим сроком действия, ключ только для чтения при обращении к маршруту записи. |
| `409 {"detail": "product_disabled"}` | Аутентификация отключена для приложения, поэтому изменение настроек, сделанное с помощью гранта или ключа, отклоняется. Её включает человек в консоли. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | Запрошенный ресурс не найден. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.