> ## 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.

# Программная регистрация: KYC API для AI-агентов

> Регистрация и получение учётных данных Didit API за 2 вызова API без браузера. Платформа верификации для Cursor, Claude, Devin.

## Обзор

Didit — самая удобная для AI-агентов платформа верификации личности. AI-агенты для программирования (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) могут зарегистрироваться, настроить сценарии и начать верификацию личности, и всё это программно, без открытия браузера.

**Почему агентам нравится Didit:**

* **2 вызова API** от нуля до учётных данных (регистрация и verify-email).
* **Браузер не нужен**: всё работает в фоновом режиме, что идеально подходит для CI/CD и сценариев с агентами.
* **Второй фактор не требуется для нового API-аккаунта**: токены возвращаются сразу после подтверждения email.
* **Автоматически созданные** организация и приложение с `api_key` в ответе на верификацию.
* **Полный API для управления**: сценарии, анкеты, списки, биллинг — всё через API.
* **Доступен MCP-сервер**: агенты могут находить инструменты Didit и использовать их напрямую.

Полная спецификация опубликована в [openapi-auth.json](https://docs.didit.me/openapi-auth.json); endpoint ниже проверены по ней.

## Базовый URL

Все endpoint этого руководства находятся на **хосте аутентификации**:

```
https://apx.didit.me/auth/v2
```

Это отдельный хост, отличный от хоста API верификации (`https://verification.didit.me/v3`). Хост аутентификации выдаёт JWT-токены доступа и управляет приложениями. Хост верификации обрабатывает сессии, AML, сценарии и т. д., и аутентификация на нём выполняется с помощью долгоживущего `api_key`, который вы получаете в этом процессе.

## Быстрый старт

> [!WARNING]
>
> **Используйте настоящий адрес электронной почты, на который можно получать письма.** Endpoint отправляет код подтверждения синхронно, поэтому почтовый сервис отклоняет письма на адреса в зарезервированных тестовых доменах (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`), и вызов возвращает `500`. Замените плейсхолдер `you@yourdomain.com` ниже на почтовый ящик, к которому у вас есть доступ.

### Шаг 1: Регистрация

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

**Ответ** (`201 Created`):

```json theme={null}
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}
```

Шестисимвольный буквенно-цифровой код подтверждения (например, `A3K9F2`) отправляется на адрес электронной почты. **Код истекает через 10 минут после отправки.** Если срок истёк, снова вызовите этот endpoint с тем же email и паролем: для ещё не подтверждённого аккаунта он вернёт `200` с текстом `"A new verification code has been sent to your email."` и новым кодом. Отдельный endpoint `POST /programmatic/resend-otp/` (тело запроса: `{"email", "password"}`) также повторно отправляет код, между отправками действует ограничение 60 секунд. Оба маршрута используют общий лимит запросов на регистрацию, описанный ниже.

### Шаг 2: Подтверждение кода и получение учётных данных

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
```

**Ответ** (`200 OK`):

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
```

Теперь у вас есть всё необходимое. Сохраните `application.api_key` в безопасном месте и передавайте его в заголовке `x-api-key` в каждом вызове API верификации.

> [!NOTE]
>
> Токены — это **JWT, подписанные RS256**. Значение `expires_in` по умолчанию равно **86400 секундам (24 часа)**. Токен доступа нужен только для endpoint управления на `apx.didit.me/auth/v2`. Трафик API верификации на `verification.didit.me/v3` аутентифицируется долгоживущим `api_key`, а не JWT.

### Шаг 3: Использование API

```bash theme={null}
curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Последующие входы

При последующих входах с любого устройства обменяйте email и пароль на новый JWT:

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

Endpoint сразу возвращает `access_token` и `refresh_token`, браузер не нужен. Затем вызовите `GET /organizations/me/`, чтобы узнать свой `org_id` (`uuid` организации), после чего `GET /organizations/me/{org_id}/applications/`, чтобы получить список приложений организации (`uuid` каждой записи является `app_id`), и наконец `GET /organizations/me/{org_id}/applications/{app_id}/`, чтобы получить `api_key`.

> [!NOTE]
>
> Учётные записи, созданные в консоли с email и паролем, также могут использовать `POST /programmatic/login/` после подтверждения email. Для учётных записей консоли, использующих только OAuth, перед использованием этого входа без браузера необходимо задать пароль.

### Что делать, если для входа требуется что-то ещё

`POST /programmatic/login/` возвращает токены только тогда, когда у аккаунта нет второго фактора. Возможны ещё три варианта ответа, и агент, автоматизирующий вход, должен обрабатывать каждый из них:

| Аккаунт | Ответ |
| - | - |
| Есть приложение-аутентификатор или ключ доступа | `200` с `{"2fa_required": true, "temp_token": "...", "has_passkeys": true, "has_authenticator": false}` и без токенов |
| Организация требует SSO | `403` с `{"error": "sso_required", "message": "...", "organization_name": "...", "organization_slug": "...", "sso_url": "/sso/<slug>"}` |
| Аккаунт был восстановлен и пока не имеет способа входа | `403` с `"code": "recovery_setup_required"`; ссылка на настройку способа входа отправляется на адрес аккаунта |

Для автоматизации используйте API-ключ, так как он не требует входа. Аккаунт с вторым фактором не может завершить вход через этот endpoint.

## Требования к паролю

Проверяются на стороне сервера, **по одному правилу за раз**: первая ошибка прерывает проверку и возвращает ошибку в виде простого массива, например `["Password must contain at least one uppercase letter."]`. (Другие ошибки валидации на этом endpoint используют оболочку с ключом поля `{"password": [...]}`. Формат простого массива для правил сложности пароля — известная несогласованность на стороне сервера. В клиентском коде обрабатывайте его как `{"password": [...]}`.)

| Правило | Подробности |
| - | - |
| Минимальная длина | 8 символов |
| Заглавная буква | Не менее одной из `A–Z` |
| Строчная буква | Не менее одной из `a–z` |
| Цифра | Не менее одной из `0–9` |
| Специальный символ | Не менее одного из `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## Лимиты запросов и блокировки

Три независимых механизма защищают хост аутентификации. Любой из них может вызвать ответ `429`. Заголовок ответа `Retry-After` сообщает, сколько нужно ждать перед повторной попыткой.

| Сценарий | Лимит |
| - | - |
| Регистрация | **5** попыток на **IP** в **час** (общий лимит с `POST /programmatic/resend-otp/`). |
| Подтверждение email | **10** попыток ввода кода на **email** в **час** и **50** на исходный **IP** в **час**, а также экспоненциальная задержка между попытками (30 с, удваивается после каждой неудачной попытки, но не более 1 часа). |
| Вход (IP) | **20** попыток на **IP** в **минуту** и **100** на **IP** в **час**. |
| Вход (email) | Прогрессивная блокировка аккаунта: **5** подряд идущих неудачных попыток → блокировка на 15 минут; **10** → 1 час; **20** → 24 часа. |

Тело ответа `429` выглядит так:

```json theme={null}
{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }
```

Лимиты Verification API (например, 600 сессий в минуту) независимы от этих и описаны в разделе [Ограничение частоты запросов](https://docs.didit.me/ru/integration/rate-limiting.md).

## Управление приложениями

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

Это идеальный вариант для **реселлеров**, которые хотят иметь отдельное приложение для каждого клиента. У каждого приложения есть собственные `client_id`, `api_key`, метаданные и настройки. Это также полезно, если в вашей организации есть разные продукты, бренды, регионы, среды или сценарии использования, которые нужно держать раздельно.

```bash theme={null}
# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'
```

Для просмотра списка, создания или обновления приложений пользователь должен быть **владельцем** или **администратором** целевой организации. В противном случае возвращается ответ `403`.

## Что могут делать агенты после регистрации

С помощью `api_key` агенты получают полный доступ к Verification API. Аудированные пути на `https://verification.didit.me/v3`:

| API | Что делает |
| - | - |
| `POST /v3/session/` | Создать сессию верификации. |
| `GET /v3/sessions/` | Получить список сессий. |
| `GET /v3/session/{id}/decision/` | Получить решение V3 (массивы во множественном числе; см. раздел «Модели данных»). |
| `GET /v3/workflows/` | Получить список сценариев верификации. |
| `GET /v3/questionnaires/` | Получить список настраиваемых анкет. |
| `GET /v3/users/` | Получить список конечных пользователей (индексируются по `vendor_data`). |
| `GET /v3/billing/balance/` | Проверить баланс кредитов. |
| `POST /v3/billing/top-up/` | Пополнить баланс кредитов. |
| `GET /v3/webhook/destinations/` | Управлять адресами назначения webhook (получение списка, создание, обновление, удаление). |

Полный перечень см. в [справочнике Management API](https://docs.didit.me/ru/sessions-api/management-api.md).

## Интеграция с MCP-сервером

Для наилучшей работы агентов используйте размещённый MCP-сервер Didit по адресу `https://mcp.didit.me/mcp`. API-ключ не требуется: при первом подключении клиент откроет браузер, вы нажмёте **Войти через Didit** (OAuth 2.1 с PKCE), и сервер будет действовать от вашего имени с правами вашей роли в консоли. Клиенты с нативной поддержкой удалённых MCP-серверов (Cursor, VS Code) используют эту запись. Claude в вебе и Desktop добавляют её как пользовательский коннектор:

```json theme={null}
{
  "mcpServers": {
    "didit": {
      "url": "https://mcp.didit.me/mcp"
    }
  }
}
```

Claude Code: `claude mcp add --transport http didit https://mcp.didit.me/mcp`. Клиенты, которые работают только через stdio (Windsurf, Zed), подключаются через мост `mcp-remote`, который выполняет для вас процесс OAuth.

API-ключ, который вы получаете в процессе регистрации выше, предназначен для вызова REST API с вашего бэкенда. MCP его никогда не использует. Подробности см. в [обзоре MCP](https://docs.didit.me/ru/integration/mcp/overview.md) и в [инструкциях по установке для каждого клиента](https://docs.didit.me/ru/integration/mcp/installation.md).

## Справочник по форматам ошибок

Все endpoint `apx.didit.me/auth/v2` используют одни и те же три формата ответов (см. `openapi-auth.json`):

* **Валидация на уровне полей:** `{"field": ["message", ...]}` с HTTP `400`.
* **Валидация на уровне формы** (в первую очередь сложность пароля и ошибки кода подтверждения): простой массив `["Invalid or expired verification code."]` без дополнительной оболочки с HTTP `400`.
* **Аутентификация и бизнес-правила:** `{"detail": "..."}` с кодами `400`, `401`, `403`, `404` или `429`. Ответы `429` содержат заголовок `Retry-After`, который сообщает, сколько нужно ждать перед повторной попыткой (тело содержит только `detail`).

Хост верификации возвращает ошибки в виде `{"detail": "..."}`, а в ответах 429 есть заголовки `X-RateLimit-*` и `Retry-After`. См. [Ограничение частоты запросов](https://docs.didit.me/ru/integration/rate-limiting.md).


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