> ## 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 Authentication API

> DiditのPOST /step-up/は、機密性の高いアクションの前にステップアップルールを適用し、required falseまたは本人向けの認証URLを返します。

> [!WARNING]
>
> Authenticationは新機能です。これらのエンドポイントはアプリケーションのissuer(`https://<name>.auth.didit.me`など)から提供され、Didit APIキーは一切受け付けません。

`return_to`に付与される`step_up`および`status`クエリパラメーターは、アプリケーションに確認を促すためのものにすぎません。処理を行う前に[ステップアップの取得](https://docs.didit.me/ja/authentication/api-reference/retrieve-step-up.md)でステップアップを読み取り、`status`が`approved`の場合にのみ処理を続行してください。


## OpenAPI

````yaml ja/openapi-authentication.json POST /step-up/
openapi: 3.0.3
info:
  title: Didit Authentication API
  version: 1.0.0
  description: >-
    Didit Authenticationのサーバー向けエンドポイントです。Didit
    Authenticationは、アプリケーションのエンドユーザー向けのサインイン製品です。Authenticationは**新しい**製品で、2026-11-01リリースで本番環境に提供されます。


    ## ベースURL


    各アプリケーションはそれぞれ独自のOpenID
    Connect発行者（issuer）であり、以下のすべてのエンドポイントはその発行者のルートで提供されます。


    -
    本番環境のアプリケーションでは`https://<name>.auth.didit.me`、サンドボックスのアプリケーションでは`https://<name>.sandbox.auth.didit.me`。

    -
    有効化された独自のカスタムドメイン。有効化されると、デフォルトのホストに代わってこのドメインが発行者になります。新しいトークンの`iss`にはこのドメインが記載され、ディスカバリーはこのドメインを指し、公開可能キー（publishable
    key）が変わります。デフォルトのホストで発行されたアクセストークンは、更新されるまで`/session/`、`/step-up/`、`/monitoring-token/`で失敗します。


    本番環境とサンドボックスは別々のアプリケーションであるため、それぞれ別の発行者となり、キーも別です。公開可能キーは、`pk_live_`（本番環境）または`pk_test_`（サンドボックス）の後に、末尾のスラッシュを除いた発行者をパディングなしのbase64urlでエンコードした文字列が続く形式です。デコードすると発行者がわかります。これは公開識別子であり、認証情報ではありません。


    同じJSONエンドポイントは`https://apx.didit.me/auth/v2/authentication/{application_id}/`でも提供されます。どのアドレスから発行されたかにかかわらず、トークンには常に上記の発行者が記載されます。


    ## 認証情報


    これらのエンドポイントは、DiditのAPIキーやコンソールトークンを受け付けることはありません。


    - ディスカバリー、JWKS、`POST
    /token/`には認証情報は不要です。クライアントはパブリッククライアントです。クライアントシークレットはなく、認可コードはそのPKCE検証子（`S256`）に紐付けられます。`client_id`はアプリケーションIDです。

    -
    `/session/`、`/step-up/`、`/monitoring-token/`には本人のアクセストークンを渡します（`Authorization:
    Bearer
    <access_token>`）。呼び出しが成功するたびにセッションのアクティビティとしてカウントされるため、セッションのアイドルタイムアウトがリセットされます。


    ## リクエストボディ


    ボディを受け取るすべてのエンドポイントは、JSON、フォームエンコード、マルチパートのボディを受け付けます。このドキュメントではJSONを記載し、`POST
    /token/`についてはOAuthクライアントが送信する形式であるフォームエンコードも記載します。エンドポイントが受け付けないフィールドには`400
    {"<field>": "unknown_field"}`が返されます。


    ## トークン


    - **アクセストークン**：ヘッダーが`typ: at+jwt`のES256
    JWTで、有効期間は最大5分であり、セッションの有効期間を超えることはありません。クレーム：`AccessTokenClaims`。

    - **IDトークン**：ヘッダーが`typ: JWT`のES256
    JWTです。クレーム：`IDTokenClaims`。アクセストークンとして受け付けられることはありません。

    -
    **リフレッシュトークン**：使用するたびにローテーションされるランダムな文字列です。使用済みのリフレッシュトークンを再度送信すると、セッションが取り消されます。


    トークンは`GET
    /.well-known/jwks.json`のキーで検証してください。アルゴリズムは`ES256`でなければならず、`typ`はトークンの種類と、`iss`は設定した発行者と、`aud`はアプリケーションIDと一致しなければなりません。オフライン検証では、取り消されたセッションはそのアクセストークンの有効期限が切れた時点で初めて検出されます。即時に確認するには`GET
    /session/`を使用します。


    ## エラー


    | ボディ | 発生条件 |

    | --- | --- |

    | `{"error": "<code>"}` | `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`。
    |

    | `{"<field>": ["<message>"]}`または`{"<field>": "<code>"}` |
    リクエストフィールドの検証に失敗しました。`non_field_errors`は複数のフィールドにまたがるルールを、`unknown_field`はエンドポイントが受け付けないフィールドを示します。
    |

    | `{"detail": "<message>"}` |
    `401`（`invalid_token`）、`403`（`origin_not_allowed`）、`404`（不明なアプリケーションまたはステップアップ）、`429`（レート制限）。また、解析できないボディには`400`（`JSON
    parse error -
    ...`）、エンドポイントが提供していないメソッドには`405`、サポートされていない`Content-Type`には`415`が返されます。 |


    `401`には`WWW-Authenticate: Bearer`も含まれ、`429`には秒単位の`Retry-After`が含まれます。


    JSON以外で返される拒否が2つあります。発行者ではないアドレスは、これらのエンドポイントに到達する前に拒否されます。たとえば、使用されていない`*.auth.didit.me`の名前には空の`404`が返されます。UUIDではない`step_up_id`には`404`ページが返されます。


    ## レート制限


    リクエストは2つのレイヤーを通過する必要があります。


    **エンドポイントの制限**：クライアントのIPアドレスごと、アプリケーションごと、エンドポイントごとにカウントされます。


    - ディスカバリーとJWKS：1分あたり1,200リクエスト、1時間あたり12,000リクエスト。

    - その他すべてのエンドポイント：1分あたり30リクエスト、1時間あたり300リクエスト。`GET`と`DELETE
    /session/`は1つのカウントを共有します。


    制限を超えた場合：`429 {"detail": "Too many requests from this IP address. Please
    wait before trying again. Expected available in 60
    seconds."}`が返されます。1時間あたりの制限では`3600 seconds`になります。


    **ボット対策**：すべての`POST`と`DELETE`に適用されます。そのバケットは、ホスト型のサインインステップを含むアプリケーションのすべての`POST`および`DELETE`リクエストで共有され、継続的に補充されます。


    - クライアントのIPアドレスごとに1分あたり60リクエスト。

    - デバイスを識別するリクエスト（ブラウザSDKやネイティブSDKが送信するもの）について、デバイスごとに1分あたり30リクエスト。

    - アプリケーション全体で、すべてのIPアドレスを合わせて1分あたり1,000リクエスト。


    バケットを超えた場合：`429 {"detail": "rate_limited Expected available in N
    seconds."}`が返されます（Nが1の場合は`1
    second.`）。IPごとのバケットはエンドポイントをまたいで適用されるため、トークン、ステップアップ、サインアウトの呼び出しを混在させる1つのアドレスは、いずれかのエンドポイントの制限に達する前にバケットを使い切る可能性があります。アプリケーションのバケットは、ブラウザを含むアプリケーションのすべてのクライアントをカウントします。


    どちらのレイヤーもエンドポイントが実行される前に応答するため、`429`を受け取ったリクエストは実行されていません。`Retry-After`の経過後に再試行してください。リフレッシュも同様です。


    ## ブラウザからのリクエスト


    `Origin`ヘッダーを含むリクエストは、アプリケーション自身のオリジンまたは許可されたオリジンのいずれかから送信されたものでなければならず、そうでない場合は`403
    origin_not_allowed`が返されます。サーバー間のリクエストは`Origin`を送信しません。


    ## このドキュメントの対象外


    これらのルートは、ホスト型ページ、ブラウザSDKとネイティブ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/`。AIエージェントのアクセストークンをリアルタイムで確認する`GET
    /agents/session/`も含みます。エージェントアクセスは、このバージョンの仕様には含まれません。

    - Authenticationのコンソール管理API。コンソールセッションを使用します。


    AuthenticationのイベントはまだWebhookとして配信されないため、このドキュメントではWebhookを定義していません。
servers:
  - url: https://{issuer}
    description: お客様のアプリケーションの発行者で、そのサインインオリジンです。
    variables:
      issuer:
        default: your-app.auth.didit.me
        description: >-
          発行者のホストです。`<name>.auth.didit.me`(本番環境)、`<name>.sandbox.auth.didit.me`(サンドボックス)、または有効なカスタムドメインです。
security: []
tags:
  - name: Issuer
    description: トークンを検証するためのディスカバリー情報と署名鍵です。
  - name: Tokens
    description: 認可コードグラントとリフレッシュグラント。
  - name: Sessions
    description: アクセストークンに紐づくセッションを確認して終了します。
  - name: Step-ups
    description: 機密性の高いアクションの前に行う認証。
  - name: Monitoring
    description: トランザクションモニタリングイベント用のデバイス認証情報です。
paths:
  /step-up/:
    post:
      tags:
        - Step-ups
      summary: ステップアップを作成
      description: >-
        アプリケーションに設定したステップアップルールに基づき、機密性の高いアクションの前に本人の認証が必要かどうかを確認します。


        - `200 {"required": false}`: 適用されるルールはありません。そのまま続行してください。

        - `201`:
        本人を`verification_url`に誘導してください。本人は`step_up=<id>&status=approved`を付けて`return_to`に戻りますが、このクエリは何の証明にもなりません。`GET
        /step-up/{step_up_id}/`でステップアップを読み取り、`approved`の場合にのみ処理を実行してください。


        ステップアップが失敗時に通過を許可することはありません。認証が利用できない場合、アクションはブロックされたままになります。
      operationId: authentication_create_step_up
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepUpRequest'
            examples:
              Payout:
                summary: 支払いの前
                value:
                  action: payout
                  amount: '900.00'
                  currency: USD
                  return_to: https://app.example.com/payouts/confirm
              Bank:
                summary: 銀行口座の変更前
                value:
                  action: bank
                  return_to: https://app.example.com/settings/bank
      responses:
        '200':
          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/StepUpNotRequired'
              examples:
                NotRequired:
                  summary: 続行
                  value:
                    required: false
        '201':
          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/StepUpRequired'
              examples:
                Required:
                  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'
                    required: true
                    verification_url: >-
                      https://your-app.auth.didit.me/verify/?verification=1nSX7HJCXAP9XPA9AeJfQxIuPk2GkG0dGSOzCA2Zpww
                    expires_in: 1800
        '400':
          description: >-
            フィールドが欠落しているか無効です。`return_to:
            invalid_redirect_uri`は、ルールが適用され、かつ`return_to`がアプリケーションのリダイレクトURIのいずれでもないことを意味します。
          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/FieldErrors'
              examples:
                MissingAmount:
                  summary: 金額のない払い出し
                  value:
                    amount:
                      - required
                InvalidReturnTo:
                  summary: 未登録のreturn_to
                  value:
                    return_to: invalid_redirect_uri
                UnknownAction:
                  summary: サポートされていないアクション
                  value:
                    action:
                      - '"withdraw" is not a valid choice.'
        '401':
          $ref: '#/components/responses/InvalidToken'
        '403':
          $ref: '#/components/responses/OriginNotAllowed'
        '404':
          $ref: '#/components/responses/ApplicationNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
      security:
        - AccessToken: []
components:
  schemas:
    StepUpRequest:
      type: object
      description: 対象者がこれから実行しようとしている機密性の高いアクションです。
      required:
        - action
        - return_to
      additionalProperties: false
      properties:
        action:
          type: string
          enum:
            - payout
            - bank
            - contact
          description: >-
            `payout`（出金または送金）、`bank`（銀行口座の追加または変更）、または`contact`（メールアドレスまたは電話番号の変更）です。出金・送金では、新しいデバイスに関するルールも適用されます。
        amount:
          type: string
          pattern: ^[0-9]{1,16}(\.[0-9]{1,2})?$
          description: '`payout`では必須：金額（小数点以下2桁まで）。JSONの数値も受け付けます。'
          example: '900.00'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: '`amount`のISO 4217通貨コード。デフォルトは支払いルールの通貨です。別の通貨での支払いは常にチェックされます。'
          example: USD
        return_to:
          type: string
          maxLength: 2048
          description: >-
            本人が検証後に戻る先で、`step_up=<id>&status=approved`が付加されます。ルールが適用される場合は、アプリケーションのリダイレクトURIのいずれかである必要があります。適用されるルールがない場合はチェックされません。
          example: https://app.example.com/payouts/confirm
    StepUpNotRequired:
      type: object
      description: 適用されるルールはありません。アクションを続行してください。
      required:
        - required
      properties:
        required:
          type: boolean
          enum:
            - false
    StepUpRequired:
      description: 新しいステップアップ。本人を`verification_url`に誘導してください。
      allOf:
        - $ref: '#/components/schemas/StepUp'
        - type: object
          required:
            - required
            - verification_url
            - expires_in
          properties:
            required:
              type: boolean
              enum:
                - true
            verification_url:
              type: string
              format: uri
              description: >-
                本人が認証を行うホスト型ページです。本人のブラウザで開いてください。ステップアップが承認されるか期限切れになるまで有効なため、却下された人もこのページから再試行できます。
              example: >-
                https://your-app.auth.didit.me/verify/?verification=1nSX7HJCXAP9XPA9AeJfQxIuPk2GkG0dGSOzCA2Zpww
            expires_in:
              type: integer
              description: ステップアップが有効な秒数：1800。
              example: 1800
    FieldErrors:
      title: Field errors
      type: object
      description: >-
        フィールドごとのバリデーションエラー。値はメッセージのリスト、または単一のコード（`unknown_field`、`invalid_redirect_uri`）です。`non_field_errors`には複数のフィールドにまたがるルールのエラーが入ります。
      additionalProperties:
        oneOf:
          - type: string
          - type: array
            items:
              type: string
    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がまだその人物の顔を保持していない場合、本人が`verification_url`を開いた時点で`selfie`は`full_id`に切り替わります。
          example: selfie
        status:
          type: string
          enum:
            - pending
            - review
            - approved
            - declined
            - expired
            - superseded
          description: >-
            `approved`の場合にのみ処理を進めてください。`review`は、チームによるレビューを待っている状態です。`verification_url`が有効な間、`declined`は確定ではありません。本人が再試行でき、ステップアップは`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: 支払額（小数点以下2桁）。
          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分後。ステップアップを読み取ると、まずその検証で得られた結果が取得されるため、この時間を過ぎても`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ポリシーを満たさなくなった、またはその人物がブロックされたかメールアドレスが未認証になっています。もう一度サインインを行ってもらってください。
      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: 拒否されたアクセストークン
              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: 許可されていないオリジンです
              value:
                detail: origin_not_allowed
    ApplicationNotFound:
      description: >-
        このアドレスはアプリケーションに属していますが、そのアプリケーションでAuthenticationが有効になっていません。`apx.didit.me`のアドレスでは、アプリケーションIDが不明です。どのアプリケーションにも属さないアドレスはエンドポイントに到達する前に拒否され、そのレスポンスはJSONではありません。
      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:
            ApplicationNotFound:
              summary: 不明なアプリケーション
              value:
                detail: No Configuration matches the given query.
    RateLimited:
      description: >-
        このエンドポイントに対するこのIPアドレスからのリクエストが多すぎるか、`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: エンドポイントの制限
              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/`から取得したこの人物のアクセストークンです。ヘッダーが`typ: at+jwt`のES256
        JWTで、有効期間は最長5分です。DiditのAPIキーではありません。

````

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