openapi: 3.0.3
info:
  title: API キー発行
  version: v1
  description: |
    API キー発行するためのエンドポイントを提供しています。マイページに記載されたサービスIDとサービスパスワードから API キーを発行できます。また、マイページ上で「API キー発行可能」と設定して発行した API キーでも、API キーを発行することができます。

    - API キーは、アプリケーションが AmiVoice API 音声認識サービスを利用するための**サービス認証キー文字列**です。
    - **発行日時と有効時間**にもとづいた**有効期限日時**や、**利用可能な IP アドレス**を必要に応じて設定することができます。

servers:
  - url: https://acp-api.amivoice.com

tags:
  - name: issue
    x-displayName: API キー発行

paths:
  /issue_service_authorization:
    post:
      tags:
        - issue
      summary: API キー発行
      operationId: issueServiceAuthorization
      security:
        - {}
        - bearerAuth: []
      description: |
        API キーを発行します。

        `sid`と`spw`のペア、もしくは`authorization`（`Authorization`ヘッダーに指定する API キー）のいずれかが必須です。

        :::caution
        `sid`と`spw`はリクエストボディに`application/x-www-form-urlencoded`形式で設定してください。クエリパラメータ（URL の末尾に`?`を付けて記載する方法）では指定しないでください。
        :::

        :::caution
        サービスパスワードとマイページへのログイン用のパスワードは異なります。
        :::

        :::caution
        サービス ID やサービスパスワードが間違っていても、API キーが発行されます。この不正な API キーを使用して音声認識サービスに接続すると、認証エラーになります。エラーメッセージはインタフェースによって異なります。

        **HTTPインタフェースの場合**

        サービス ID、サービスパスワードのいずれかが誤っている場合、以下のエラーを返します。

        ```json
        {
            "code":"-",
            "message":"received illegal service authorization"
        }
        ```

        **WebSocketインタフェースの場合**

        サービス ID、サービスパスワードのいずれかが誤っている場合、以下のエラーを返します。

        ```text
        s can't validate service authorization
        ```
        :::
      requestBody:
        required: false
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                sid:
                  type: string
                  description: |
                    サービスID

                    マイページの接続情報に表示される サービス ID を指定します。authorization で API キーを指定する場合は、sid は指定しないでください。`authorization`を指定しない場合は必須です。
                spw:
                  type: string
                  description: |
                    サービスパスワード

                    マイページの接続情報に表示される サービスパスワード を指定します。authorization で API キーを指定する場合は、spw は指定しないでください。`authorization`を指定しない場合は必須です。
                epi:
                  type: string
                  default: "30000"
                  description: |
                    有効期限

                    発行するAPI キーの使用期限を指定します。省略時は、30000（30 秒）が設定されます。

                    以下のいずれかを指定することができます。

                    - 数値。ミリ秒単位の使用期限となります。
                    - 's' (秒間)、'm' (分間)、'h' (時間)、'd' (日数)、'w' (週間) を単位とする文字列。例えば、以下のように指定できます。

                    ```text
                    5m                  5 分間
                    2h                  2 時間
                    100d                100 日間
                    ```

                    - `yyyy(/|-)mm(/|-)dd[( |T)hh:mm:ss[.sss][[ ](Z|(+|-)zz[[:]zz])]]` 形式の時刻を表す文字列。例えば、以下のように指定できます。

                    ```text
                    2021/06/30            2021年6月30日 24時0分0秒 (2021年7月1日 0時0分0秒) まで有効
                    2021/07/00            2021年6月30日 24時0分0秒 (2021年7月1日 0時0分0秒) まで有効
                    2021/05/15 12:05:30   2021年5月15日 12時5分30秒 まで有効
                    ```
                ipa:
                  type: string
                  description: |
                    接続元IPアドレス

                    API キーを利用できるクライアントのIPアドレスに制限を設けることができます。
                    以下のいずれかを指定することができます。

                    - 空文字列
                    - スペースまたは , (カンマ)を区切り文字とする複数の IPv4 CIDR 形式の IP アドレスを表す文字列。例えば、以下のように指定できます。

                    ```text
                    10.1.2.34
                    192.168.0.0/16
                    150.249.206.220 150.249.236.100/31
                    ```
      responses:
        "200":
          description: |
            API キー文字列を返します。
          content:
            text/plain:
              schema:
                type: string
                description: API キー文字列
        "400":
          description: |
            失敗時はエラーメッセージを返します。

            | エラーメッセージ | エラーの状況 |
            |---|---|
            | Invalid Authorization Header | `Authorization`ヘッダーが`Bearer `で始まらない場合 |
            | Invalid appkey | `authorization`で指定した API キーが正しくない場合（API キーの認証ができない） |
            | Dont issue appkey | `authorization`で指定した API キーが「API キー発行可能」と設定されていない場合、もしくは無効化されている場合 |

            何もレスポンスが無い場合は、必須項目が指定されていない可能性がありますので、パラメータをチェックしてください。
          content:
            text/plain:
              schema:
                type: string
                description: エラーメッセージ
              example: "Invalid Authorization Header"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        マイページ上で「API キー発行可能」と設定して発行した API キーを`Authorization`ヘッダーに指定します。sid と spw を指定する場合は不要です。

        ```text
        Authorization: Bearer {APIキー}
        ```
