> ## 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. # Получить статус Step-Up | Didit Authentication API > GET /step-up/{step_up_id}/ возвращает статус, метод и уровень step-up в Didit. Выполняйте чувствительное действие, только если статус — одобрена. > [!WARNING] > > Аутентификация появилась недавно. Эти endpoint обслуживаются эмитентом вашего приложения, например `https://.auth.didit.me`, и никогда не принимают ваш API-ключ Didit. Step-up принадлежит сессии, которая его создала: токен доступа другой сессии получает `404`. Step-up в статусе `pending` отображается как `expired` по истечении 30 минут. ## OpenAPI ````yaml ru/openapi-authentication.json GET /step-up/{step_up_id}/ openapi: 3.0.3 info: title: Didit Authentication API version: 1.0.0 description: >- Серверные endpoints Didit Authentication, продукта для входа конечных пользователей вашего приложения. Authentication является **новым** продуктом, который выходит в продакшн в релизе 2026-11-01. ## Базовый URL Каждое приложение является собственным издателем (issuer) OpenID Connect, и каждый приведенный ниже endpoint обслуживается в корне этого издателя: - `https://.auth.didit.me` для продакшн-приложения или `https://.sandbox.auth.didit.me` для приложения в песочнице. - Ваш собственный кастомный домен после его активации. В этом случае он заменяет хост по умолчанию в качестве издателя: новые токены указывают его в `iss`, discovery указывает на него, а публичный ключ (publishable key) меняется. Access token, выпущенные под хостом по умолчанию, возвращают ошибку при вызове `/session/`, `/step-up/` и `/monitoring-token/` до тех пор, пока не будут обновлены. Продакшн и песочница являются раздельными приложениями, поэтому они представляют собой отдельных издателей с раздельными ключами. Публичный ключ состоит из префикса `pk_live_` (продакшн) или `pk_test_` (песочница), за которым следует base64url-кодировка издателя без паддинга и без завершающего слеша: декодируйте его, чтобы узнать издателя. Это публичный идентификатор, а не учетные данные. Те же JSON endpoints также обслуживаются по адресу `https://apx.didit.me/auth/v2/authentication/{application_id}/`. Токены всегда указывают издателя, описанного выше, независимо от адреса, через который они были выпущены. ## Учетные данные Эти endpoints никогда не принимают ваш API-ключ Didit или token консоли. - Discovery, JWKS и `POST /token/` не требуют учетных данных. Клиенты являются публичными: секрет клиента (client secret) отсутствует, а код авторизации привязан к верификатору PKCE (`S256`). `client_id` является идентификатором вашего приложения (application ID). - `/session/`, `/step-up/` и `/monitoring-token/` принимают access token пользователя: `Authorization: Bearer `. Каждый успешный вызов считается активностью в сессии и сбрасывает таймаут неактивности сессии. ## Тела запросов Каждый endpoint, принимающий тело запроса, поддерживает JSON, form-encoded и multipart. В этом документе приведены JSON, а также form-encoded для `POST /token/`, как его отправляют OAuth-клиенты. Если endpoint не принимает поле, возвращается `400 {"": "unknown_field"}`. ## Токены - **Access token**: JWT с алгоритмом ES256 и заголовком `typ: at+jwt`, действительный не более 5 минут и не дольше самой сессии. Утверждения: `AccessTokenClaims`. - **ID token**: JWT с алгоритмом ES256 и заголовком `typ: JWT`. Утверждения: `IDTokenClaims`. Он никогда не принимается в качестве access token. - **Refresh token**: случайная строка, которая ротируется при каждом использовании. Повторная отправка уже использованного refresh token приводит к отзыву сессии. Проверяйте token с помощью ключей из `GET /.well-known/jwks.json`: алгоритм должен быть `ES256`, `typ` должен соответствовать типу токена, `iss` должен совпадать с настроенным вами издателем, а `aud` с идентификатором вашего приложения. Офлайн-проверка распознает отозванную сессию только после истечения срока действия ее access token; `GET /session/` выполняет мгновенную проверку. ## Ошибки | Тело | Когда возвращается | | --- | --- | | `{"error": ""}` | Ошибки от `POST /token/`, все со статусом `400`, в формате тела [RFC 6749 раздел 5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2): `invalid_grant`, `invalid_client` и Didit `mfa_required`. Ошибки сервиса: `temporarily_unavailable`, `monitoring_unavailable`, `monitoring_disabled`. | | `{"": [""]}` или `{"": ""}` | Поле запроса не прошло валидацию. `non_field_errors` указывает на правило для нескольких полей, а `unknown_field` указывает на поле, которое endpoint не принимает. | | `{"detail": ""}` | `401` (`invalid_token`), `403` (`origin_not_allowed`), `404` (неизвестное приложение или step-up) и `429` (лимит запросов). Также `400` для тела, которое невозможно распарсить (`JSON parse error - ...`), `405` для метода, который endpoint не поддерживает, и `415` для неподдерживаемого `Content-Type`. | Ответ `401` также содержит заголовок `WWW-Authenticate: Bearer`, а `429` содержит `Retry-After` в секундах. Два отказа не возвращают JSON. Запрос к адресу, не являющемуся издателем, отклоняется до попадания на эти endpoints, например, пустым ответом `404` для неиспользуемого имени `*.auth.didit.me`. Если `step_up_id` не является UUID, возвращается страница `404`. ## Лимиты запросов Запрос должен пройти два уровня проверок. **Лимиты endpoints**, рассчитываемые на IP-адрес клиента, на приложение и на endpoint: - Discovery и JWKS: 1 200 запросов в минуту и 12 000 в час. - Все остальные endpoints: 30 запросов в минуту и 300 в час. `GET` и `DELETE /session/` используют общий счетчик. Превышение лимита: `429 {"detail": "Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds."}`, или `3600 seconds` для часового лимита. **Защита от ботов**, применяется к каждому запросу `POST` и `DELETE`. Её лимитные корзины являются общими для всех запросов `POST` и `DELETE` приложения, включая размещённые шаги входа, и пополняются непрерывно: - 60 запросов в минуту на IP-адрес клиента. - 30 запросов в минуту на устройство для запросов, которые идентифицируют устройство, как это делают браузерные и нативные SDK. - 3 000 запросов в минуту для всего приложения со всех IP-адресов. Обновления токенов (`POST /token/` с `grant_type=refresh_token`) вместо этого используют отдельную корзину: 6 000 в минуту для всего приложения. Превышение корзины: `429 {"detail": "rate_limited Expected available in N seconds."}` (`1 second.`, когда N равно 1). Корзина на IP-адрес действует для всех endpoints, поэтому один адрес, отправляющий вперемешку запросы на получение токена, step-up и выход из системы, может исчерпать ее до достижения любого лимита endpoint. Корзина приложения учитывает каждого клиента приложения, включая браузеры. Оба уровня возвращают ответ до выполнения endpoint, поэтому запрос, получивший статус `429`, не был выполнен: повторите его по прошествии времени из `Retry-After`, включая запросы на обновление токена. ## Браузерные запросы Запрос, содержащий заголовок `Origin`, должен исходить из одного из собственных источников приложения или из списка его разрешённых источников, иначе он возвращает ошибку `403 origin_not_allowed`. Межсерверные запросы (server-to-server) не отправляют `Origin`. ## Не рассматривается в этом документе Эти маршруты обслуживают размещенные страницы, браузерные и нативные SDK, а также AI-агентов. Они не входят в серверный контракт, и серверные SDK их не вызывают: - Шаги входа: `POST /authorize/`, `POST /password/`, `/email/*`, `/phone/*`, `/password-reset/*`, `/passkeys/*`, `/mfa/*`, `/social/*` и `/protection/complete/`. - Размещенные страницы и обратные вызовы: `/sign-in`, `/magic`, `/invite`, `/reset`, `/verify/`, `/sso/*`, `/wallet/callback/`, `/logo/` и файлы ассоциации нативных приложений в `/.well-known/`. - Доступ для агентов: `/agents/*` и `/grants/`, включая `GET /agents/session/`, оперативную проверку access token AI-агента. Доступ для агентов не входит в эту версию контракта. - API управления в консоли для Authentication, принимающий сессии консоли. События Authentication пока не доставляются через webhook, поэтому в этом документе webhook не описан. servers: - url: https://{issuer} description: 'Эмитент вашего приложения: его источник авторизации.' variables: issuer: default: your-app.auth.didit.me description: >- Хост эмитента: `.auth.didit.me` (продакшн), `.sandbox.auth.didit.me` (песочница) или ваш активный кастомный домен. security: [] tags: - name: Issuer description: Ключи обнаружения и подписи для проверки токенов. - name: Tokens description: Гранты authorization code и refresh. - name: Sessions description: Проверить и завершить сессию, связанную с токеном доступа. - name: Step-ups description: Верификация перед выполнением конфиденциального действия. - name: Monitoring description: Учётные данные устройства для событий мониторинга транзакций. paths: /step-up/{step_up_id}/: get: tags: - Step-ups summary: Получить дополнительную проверку (step-up) description: >- Текущий статус дополнительной проверки (step-up). Вызывайте с токеном доступа той же сессии, которая создала шаг, и выполняйте действия только при значении `status`, равном `approved`. operationId: authentication_retrieve_step_up parameters: - name: step_up_id in: path required: true description: >- Значение `id` из `POST /step-up/`, также являющееся параметром запроса `step_up` в вашем `return_to`. Если значение не является UUID, возвращается страница с ошибкой `404`, а не JSON. schema: type: string format: uuid example: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 responses: '200': description: Дополнительная проверка (step-up). headers: Cache-Control: description: 'Всегда `no-store`: никогда не кэшируйте этот ответ.' schema: type: string example: no-store Pragma: description: Всегда `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/StepUp' examples: Approved: summary: 'Одобрена: продолжайте' value: id: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: payout method: selfie status: approved level: liveness_face_match amount: '900.00' currency: USD created_at: '2026-10-17T10:41:14.894632Z' completed_at: '2026-10-17T10:43:02.118204Z' expires_at: '2026-10-17T11:11:14.894581Z' Pending: summary: Ещё не завершено value: id: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: payout method: selfie status: pending level: null amount: '900.00' currency: USD created_at: '2026-10-17T10:41:14.894632Z' completed_at: null expires_at: '2026-10-17T11:11:14.894581Z' '401': $ref: '#/components/responses/InvalidToken' '403': $ref: '#/components/responses/OriginNotAllowed' '404': description: >- Ни одна дополнительная проверка с этим ID не принадлежит этой сессии, либо приложение неизвестно. headers: Cache-Control: description: 'Всегда `no-store`: никогда не кэшируйте этот ответ.' schema: type: string example: no-store Pragma: description: Всегда `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: StepUpNotFound: summary: Неизвестный step-up value: detail: No VerificationCheck matches the given query. '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/TemporarilyUnavailable' security: - AccessToken: [] components: schemas: StepUp: type: object description: Верификация, которую человек должен пройти перед совершением действия. required: - id - rule - method - status - level - amount - currency - created_at - completed_at - expires_at properties: id: type: string format: uuid example: 94efc2c3-ca84-42fe-900b-6fb61669a7a1 rule: type: string enum: - payout - device - bank - contact description: >- Правило, которое запросило это действие. Если применимо несколько правил, выбирается правило с самым строгим методом. example: payout method: type: string enum: - liveness - selfie - full_id description: >- Что делает пользователь: `liveness`, `selfie` (проверка живости со сравнением с лицом, которое уже есть у Didit) или `full_id` (документ и селфи). Если у Didit ещё нет лица пользователя, `selfie` переходит в `full_id`, как только пользователь открывает `verification_url`. example: selfie status: type: string enum: - pending - review - approved - declined - expired - superseded description: >- Действуйте только при статусе `approved`. Статус `review` ожидает проверки вашей командой. Статус `declined` не является окончательным, пока действует `verification_url`: пользователь может повторить попытку, и повторная проверка вернётся в статус `pending`. Статус `superseded` означает, что другая проверка перехватила эту верификацию либо результат относился не к этой повторной проверке: создайте новую. example: pending level: type: string nullable: true enum: - liveness - liveness_face_match - full_id - null description: Уровень, достигнутый верификацией после её одобрения. example: null amount: type: string nullable: true description: Сумма выплаты, два знака после запятой. example: '900.00' currency: type: string nullable: true example: USD created_at: type: string format: date-time example: '2026-10-17T10:41:14.894632Z' completed_at: type: string format: date-time nullable: true example: null expires_at: type: string format: date-time description: >- 30 минут после создания. При чтении step-up сначала запрашивается любой результат, которого достигла его верификация, поэтому по истечении этого времени он всё ещё может возвращать `approved`, `review` или `declined`; если результат всё ещё `pending`, возвращается `expired`. example: '2026-10-17T11:11:14.894581Z' Detail: type: object required: - detail properties: detail: type: string example: invalid_token OAuthError: title: OAuth error type: object description: Ошибка OAuth (RFC 6749, раздел 5.2) или ошибка сервиса. required: - error properties: error: type: string example: invalid_grant responses: InvalidToken: description: >- Токен доступа отсутствует, некорректен, истёк, подписан другим эмитентом или ключом, является ID-токеном, токеном агента или заменён токеном обновления; либо его сессия была отозвана, завершилась по неактивности, превысила срок жизни или больше не соответствует вашей политике MFA, либо пользователь был заблокирован или его email больше не подтверждён. Отправьте пользователя на повторный вход. headers: WWW-Authenticate: description: '`Bearer`.' schema: type: string example: Bearer Cache-Control: description: 'Всегда `no-store`: никогда не кэшируйте этот ответ.' schema: type: string example: no-store Pragma: description: Всегда `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: InvalidToken: summary: Отклонённый access token value: detail: invalid_token OriginNotAllowed: description: >- Запрос содержал заголовок `Origin`, который не принадлежит приложению и не входит в его список разрешённых источников. Серверные запросы не отправляют `Origin`. headers: Cache-Control: description: 'Всегда `no-store`: никогда не кэшируйте этот ответ.' schema: type: string example: no-store Pragma: description: Всегда `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: OriginNotAllowed: summary: Источник (origin) не разрешен value: detail: origin_not_allowed RateLimited: description: >- Слишком много запросов с этого IP-адреса для данного endpoint, либо при вызове `POST` или `DELETE` исчерпан лимит защиты от ботов. Ничего не было выполнено: подождите количество секунд, указанное в `Retry-After`, затем повторите попытку. headers: Retry-After: description: Количество секунд ожидания перед повторной попыткой. schema: type: integer example: 60 Cache-Control: description: 'Всегда `no-store`: никогда не кэшируйте этот ответ.' schema: type: string example: no-store Pragma: description: Всегда `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/Detail' examples: RateLimited: summary: Лимит запросов к endpoint value: detail: >- Too many requests from this IP address. Please wait before trying again. Expected available in 60 seconds. BotProtection: summary: Лимит защиты от ботов (POST и DELETE) value: detail: rate_limited Expected available in 2 seconds. TemporarilyUnavailable: description: >- Сервис, от которого зависит запрос, временно недоступен. Повторите попытку с задержкой. headers: Cache-Control: description: 'Всегда `no-store`: никогда не кэшируйте этот ответ.' schema: type: string example: no-store Pragma: description: Всегда `no-cache`. schema: type: string example: no-cache content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: TemporarilyUnavailable: summary: Повторить попытку позже value: error: temporarily_unavailable securitySchemes: AccessToken: type: http scheme: bearer bearerFormat: JWT description: >- Токен доступа человека из `POST /token/`: JWT с алгоритмом ES256 и заголовком `typ: at+jwt`, действующий не более 5 минут. Не ваш API-ключ Didit. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.