SAKURA internet Service Principal API

openapi: 3.2.0
info:
  title: さくらのクラウドIAM Service Principal API
  version: 2.1.0
  contact:
    name: SAKURA internet Inc.
  description: さくらのクラウドIAMのAPIドキュメントです
servers:
- url: https://secure.sakura.ad.jp/cloud/api/iam/1.0
security:
- ServicePrincipalAuth: []
tags:
- name: service-principal
  x-displayName: サービスプリンシパル
  description: サービスプリンシパルに関する機能
paths:
  /service-principals:
    get:
      operationId: listServicePrincipals
      tags:
      - service-principal
      summary: サービスプリンシパル一覧を取得する
      parameters:
      - $ref: '#/components/parameters/PaginationPage'
      - $ref: '#/components/parameters/PaginationPerPage'
      - name: project_id
        in: query
        description: プロジェクトID
        schema:
          type: integer
      - name: ordering
        in: query
        description: '並び替えキー

          * `name` - サービスプリンシパル名昇順

          * `-name` - サービスプリンシパル名降順

          '
        schema:
          type: string
          enum:
          - name
          - -name
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - items
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/ServicePrincipal'
                - $ref: '#/components/schemas/Pagination'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
    post:
      operationId: createServicePrincipal
      tags:
      - service-principal
      summary: サービスプリンシパルを作成する
      requestBody:
        description: サービスプリンシパルの情報
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_id
              - name
              - description
              properties:
                project_id:
                  type: integer
                  description: プロジェクトID
                  example: 1
                name:
                  type: string
                  description: サービスプリンシパル名
                  example: Sakura Service Principal
                description:
                  type: string
                  description: サービスプリンシパルの説明
                  example: サービスプリンシパルの説明
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipal'
        '400':
          description: 不正なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http400BadRequest'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '409':
          description: プロジェクトあたりサービスプリンシパル数の上限到達
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http409Conflict'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/{service_principal_id}:
    parameters:
    - $ref: '#/components/parameters/ServicePrincipalID'
    get:
      operationId: readServicePrincipal
      tags:
      - service-principal
      summary: 指定したサービスプリンシパルを取得する
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipal'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '404':
          description: 指定したサービスプリンシパルが存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http404NotFound'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
    put:
      operationId: updateServicePrincipal
      tags:
      - service-principal
      summary: 指定したサービスプリンシパルを更新する
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: サービスプリンシパル名
                  example: Sakura Service Principal
                description:
                  type: string
                  description: サービスプリンシパルの説明
                  example: サービスプリンシパルの説明
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipal'
        '400':
          description: 不正なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http400BadRequest'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '404':
          description: 指定したサービスプリンシパルが存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http404NotFound'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
    delete:
      operationId: deleteServicePrincipal
      tags:
      - service-principal
      summary: 指定したサービスプリンシパルを削除する
      responses:
        '204':
          description: 成功
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '404':
          description: 指定したサービスプリンシパルが存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http404NotFound'
        '409':
          description: サービスプリンシパルがリソースに関連付けられている
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http409Conflict'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/oauth2/token:
    post:
      operationId: issueServicePrincipalToken
      tags:
      - service-principal
      summary: RFC 7523 (JWT Bearer Token Grant) に基づき、署名済みJWTを使って一時的なサービスプリンシパルトークンを取得する
      security: []
      description: '登録済みサービスプリンシパルキーの秘密鍵を使い、以下のようなJWTを署名してください。


        #### JWTのヘッダー


        ```json

        {

        "alg": "RS256",

        "kid": "$SERVICE_PRINCIPAL_KEY_KID",

        "typ": "JWT"

        }

        ```


        ### JWTのペイロード


        ```json

        {

        "aud": "https://secure.sakura.ad.jp/cloud/api/iam/1.0/service-principals/oauth2/token",

        "exp": 現在のUnix time + 5分,

        "iat": 現在のUnix time,

        "iss": "$SERVICE_PRINCIPAL_RESOURCE_ID",

        "sub": "$SERVICE_PRINCIPAL_RESOURCE_ID"

        }

        ```'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ServicePrincipalJWTGrantRequest'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipalOAuth2AccessToken'
        '400':
          description: 不正なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http400BadRequest'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/{service_principal_id}/keys:
    get:
      operationId: listServicePrincipalKeys
      tags:
      - service-principal
      summary: サービスプリンシパルキー一覧を取得する
      parameters:
      - $ref: '#/components/parameters/ServicePrincipalID'
      - $ref: '#/components/parameters/PaginationPage'
      - $ref: '#/components/parameters/PaginationPerPage'
      - name: ordering
        in: query
        description: '並び替えキー

          * `created_at` - 作成日時昇順

          * `-created_at` - 作成日時降順

          * `key_expires_at` - 有効期限昇順

          * `-key_expires_at` - 有効期限降順

          '
        schema:
          type: string
          enum:
          - created_at
          - -created_at
          - key_expires_at
          - -key_expires_at
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  required:
                  - items
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/ServicePrincipalKey'
                - $ref: '#/components/schemas/Pagination'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/{service_principal_id}/upload-key:
    post:
      operationId: uploadServicePrincipalKey
      tags:
      - service-principal
      summary: ユーザ生成の鍵をサービスプリンシパルキーとして登録する
      parameters:
      - $ref: '#/components/parameters/ServicePrincipalID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                public_key:
                  $ref: '#/components/schemas/ServiceprincipalKeyPublicKey'
              required:
              - public_key
      responses:
        '201':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipalKey'
        '400':
          description: 不正なリクエスト
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http400BadRequest'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '409':
          description: 上限に達している
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http409Conflict'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/{service_principal_id}/keys/{service_principal_key_id}/enable:
    post:
      operationId: enableServicePrincipalKey
      tags:
      - service-principal
      summary: 指定したサービスプリンシパルキーを有効化する
      parameters:
      - $ref: '#/components/parameters/ServicePrincipalID'
      - $ref: '#/components/parameters/ServicePrincipalKeyID'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipalKey'
              example:
                id: 00000000-0000-0000-0000-000000000000
                kid: 1234567890abcdef1234567890abcdef12345678
                status: enabled
                key_origin: user
                public_key: BEGIN PUBLIC KEY\n...\nEND PUBLIC KEY
                created_at: '2023-10-01T00:00:00Z'
                key_expires_at: '2024-10-01T00:00:00Z'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '404':
          description: 指定したサービスプリンシパルキーが存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http404NotFound'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/{service_principal_id}/keys/{service_principal_key_id}/disable:
    post:
      operationId: disableServicePrincipalKey
      tags:
      - service-principal
      summary: 指定したサービスプリンシパルキーを無効化する
      parameters:
      - $ref: '#/components/parameters/ServicePrincipalID'
      - $ref: '#/components/parameters/ServicePrincipalKeyID'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePrincipalKey'
              example:
                id: 00000000-0000-0000-0000-000000000000
                kid: 1234567890abcdef1234567890abcdef12345678
                status: disabled
                key_origin: user
                public_key: BEGIN PUBLIC KEY\n...\nEND PUBLIC KEY
                created_at: '2023-10-01T00:00:00Z'
                key_expires_at: '2024-10-01T00:00:00Z'
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '404':
          description: 指定したサービスプリンシパルキーが存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http404NotFound'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
  /service-principals/{service_principal_id}/keys/{service_principal_key_id}:
    delete:
      operationId: deleteServicePrincipalKey
      tags:
      - service-principal
      summary: 指定したサービスプリンシパルキーを削除する
      parameters:
      - $ref: '#/components/parameters/ServicePrincipalID'
      - $ref: '#/components/parameters/ServicePrincipalKeyID'
      responses:
        '204':
          description: 成功
        '401':
          description: 認証情報が無効
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http401Unauthorized'
        '403':
          description: アクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http403Forbidden'
        '404':
          description: 指定したサービスプリンシパルキーが存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http404NotFound'
        '429':
          description: APIリクエストのレートリミット超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Http429TooManyRequests'
components:
  parameters:
    ServicePrincipalKeyID:
      in: path
      name: service_principal_key_id
      description: サービスプリンシパルキーID
      required: true
      schema:
        type: string
        format: uuid
        example: 00000000-0000-0000-0000-000000000000
    PaginationPage:
      in: query
      name: page
      schema:
        type: integer
    ServicePrincipalID:
      in: path
      name: service_principal_id
      description: サービスプリンシパルID
      required: true
      schema:
        type: integer
        example: 123456789123
    PaginationPerPage:
      in: query
      name: per_page
      schema:
        type: integer
  schemas:
    Http403Forbidden:
      type: object
      required:
      - type
      - status
      - title
      - detail
      properties:
        type:
          type: string
          description: 問題を説明するドキュメントへのURI（基本的にはabout:blank）
          example: about:blank
        status:
          type: integer
          description: HTTPステータスコード
          example: 403
        title:
          type: string
          description: 問題を表す簡単な文字列
          example: permission_denied
        detail:
          type: string
          description: 問題の詳細を説明した文字列（人が読んで問題解決に繋がるような説明）
          example: このアクションを実行する権限がありません。
    ServicePrincipalJWTGrantRequest:
      type: object
      required:
      - grant_type
      - assertion
      properties:
        grant_type:
          type: string
          description: 固定値 JWT Bearer Grant Type
          enum:
          - urn:ietf:params:oauth:grant-type:jwt-bearer
          example: urn:ietf:params:oauth:grant-type:jwt-bearer
        assertion:
          type: string
          description: サービスプリンシパルキーで署名されたJWT
          example: eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLCJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
    Http409Conflict:
      type: object
      required:
      - type
      - status
      - title
      - detail
      properties:
        type:
          type: string
          description: 問題を説明するドキュメントへのURI（基本的にはabout:blank）
          example: about:blank
        status:
          type: integer
          description: HTTPステータスコード
          example: 409
        title:
          type: string
          description: 問題を表す簡単な文字列
          example: conflict
        detail:
          type: string
          description: 問題の詳細を説明した文字列（人が読んで問題解決に繋がるような説明）
          example: 状態の競合によりリクエストを処理できません。
    Pagination:
      type: object
      required:
      - count
      - next
      - previous
      properties:
        count:
          type: integer
          description: データ総数
          example: 100
        next:
          type:
          - string
          - 'null'
          format: uri
          description: 次のページへのURL
          example: https://api.example.com/?page=3&per_page=10
        previous:
          type:
          - string
          - 'null'
          format: uri
          description: 前のページへのURL
          example: https://api.example.com/?per_page=10
    Http401Unauthorized:
      type: object
      required:
      - type
      - status
      - title
      - detail
      properties:
        type:
          type: string
          description: 問題を説明するドキュメントへのURI（基本的にはabout:blank）
          example: about:blank
        status:
          type: integer
          description: HTTPステータスコード
          example: 401
        title:
          type: string
          description: 問題を表す簡単な文字列
          example: authentication_failed
        detail:
          type: string
          description: 問題の詳細を説明した文字列（人が読んで問題解決に繋がるような説明）
          example: 認証情報が含まれていません。
    Http429TooManyRequests:
      type: object
      required:
      - type
      - status
      - title
      - detail
      properties:
        type:
          type: string
          description: 問題を説明するドキュメントへのURI（基本的にはabout:blank）
          example: about:blank
        status:
          type: integer
          description: HTTPステータスコード
          example: 429
        title:
          type: string
          description: 問題を表す簡単な文字列
          example: throttled
        detail:
          type: string
          description: 問題の詳細を説明した文字列（人が読んで問題解決に繋がるような説明）
          example: リクエストの処理は絞られました。 60秒後に利用可能になります。
    ServiceprincipalKeyPublicKey:
      type: string
      description: 'PEM形式の公開鍵文字列

        RSA鍵のみをサポート

        鍵長は2048ビット以上かつ4096ビット以下をサポート

        '
      example: BEGIN PUBLIC KEY\n...\nEND PUBLIC KEY
    ServicePrincipalKey:
      type: object
      required:
      - id
      - kid
      - status
      - key_origin
      - public_key
      - created_at
      properties:
        id:
          type: string
          description: サービスプリンシパルキーID
          readOnly: true
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        kid:
          type: string
          description: 公開鍵のkid
          readOnly: true
          example: 1234567890abcdef1234567890abcdef12345678
        status:
          type: string
          description: 'サービスプリンシパルキーの状態

            * enabled 有効

            * disabled 無効

            '
          enum:
          - enabled
          - disabled
          example: enabled
        key_origin:
          type: string
          description: '鍵の生成元

            '
          readOnly: true
          enum:
          - user
          example: user
        public_key:
          $ref: '#/components/schemas/ServiceprincipalKeyPublicKey'
        created_at:
          type: string
          description: 作成日時
          example: 2024-05-01 14:30:00+00:00
        key_expires_at:
          type:
          - string
          - 'null'
          description: 有効期限
          example: 2024-05-01 14:30:00+00:00
    ServicePrincipalOAuth2AccessToken:
      type: object
      required:
      - access_token
      - token_expired_at
      properties:
        access_token:
          type: string
          description: アクセストークン
          example: abcdefghijklmnopqrstuvwxyz0123456789-._~+/ABCDEFGHIJKLMN
        token_type:
          type: string
          description: トークンの種類
          example: Bearer
        token_expired_at:
          type: string
          format: date-time
          description: アクセストークンの有効期限 (ISO 8601形式)
          example: '2021-01-01T00:00:01+09:00'
        expires_in:
          type: integer
          description: アクセストークンの有効期限（秒単位）
          example: 3600
    Http404NotFound:
      type: object
      required:
      - type
      - status
      - title
      - detail
      properties:
        type:
          type: string
          description: 問題を説明するドキュメントへのURI（基本的にはabout:blank）
          example: about:blank
        status:
          type: integer
          description: HTTPステータスコード
          example: 404
        title:
          type: string
          description: 問題を表す簡単な文字列
          example: not_found
        detail:
          type: string
          description: 問題の詳細を説明した文字列（人が読んで問題解決に繋がるような説明）
          example: 見つかりませんでした。
    Http400BadRequest:
      type: object
      required:
      - type
      - status
      - title
      - detail
      - errors
      properties:
        type:
          type: string
          description: 問題を説明するドキュメントへのURI（基本的にはabout:blank）
          example: about:blank
        status:
          type: integer
          description: HTTPステータスコード
          example: 400
        title:
          type: string
          description: 問題を表す簡単な文字列
          example: invalid
        detail:
          type: string
          description: 問題の詳細を説明した文字列（人が読んで問題解決に繋がるような説明）
          example: 不正な入力です。
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              required:
              - message
              - code
              properties:
                message:
                  type: string
                  description: エラー内容を説明した文字列
                code:
                  type: string
                  description: エラーの内容を表す文字列
            description: リクエストボディの特定キーに関するエラー
          properties:
            non_field_errors:
              type: array
              items:
                type: object
                required:
                - message
                - code
                properties:
                  message:
                    type: string
                    description: エラー内容を説明した文字列
                  code:
                    type: string
                    description: エラーの内容を表す文字列
              description: リクエストボディの特定キーに関係しないエラー
          example:
            key1:
            - message: この項目は必須です。
              code: required
            key2:
            - message: 有効な値ではありません。
              code: invalid
            key3:
            - message: この項目は少なくとも*文字以上にしてください。
              code: min_length
            key4:
            - message: この項目が*文字より長くならないようにしてください。
              code: max_length
    ServicePrincipal:
      type: object
      required:
      - id
      - project_id
      - name
      - description
      properties:
        id:
          type: integer
          description: サービスプリンシパルID
          readOnly: true
          example: 1
        project_id:
          type: integer
          description: プロジェクトID
          example: 1
        name:
          type: string
          description: サービスプリンシパル名
          example: Sakura Service Principal
        description:
          type: string
          description: サービスプリンシパルの説明
          example: サービスプリンシパルの説明
        created_at:
          type: string
          description: 作成日時
          example: 2024-05-01 14:30:00+00:00
        updated_at:
          type: string
          description: 更新日時
          example: 2024-05-02 14:30:00+00:00
  securitySchemes:
    ServicePrincipalAuth:
      description: 'サービスプリンシパル認証

        - サービスプリンシパルのアクセストークンを指定

        '
      type: http
      scheme: bearer
    ProjectApiKeyAuth:
      description: 'APIキー認証

        - ユーザー名に発行したAPIキーのアクセストークンを指定

        - パスワードに発行したAPIキーのアクセストークンシークレットを指定

        '
      type: http
      scheme: basic