openapi: 3.0.3
info:
  title: jwks
  version: 1.0.1776688313546
  description: Сервис jwks
  license:
    name: CC BY-NC-ND 4.0
    url: https://gitlab.infra.rtkit.dev/openapi/key/raw/main/LICENCE.md
tags:
  - name: key(public)
    description: Методы key. Не требуют авторизацию. Доступны из интернета
  - name: system(public)
    description: Методы system. Не требуют авторизацию. Доступны из интернета
  - name: key(internal auth)
    description: Внутренние методы. Требуют авторизацию. Доступны только во внутренней сети
paths:
  /jwks/api/v1/key/.well-known/jwks.json:
    get:
      summary: >-
        Метод получения публичных ключей.

        Возвращает три последних публичных ключа.

        Используется партнёрами, с помощью публичного ключа проверяется подпись в JWT, выпущенных платформой Ключ.

        Сценарий использования метода: https://confluence.rt.ru/pages/viewpage.action?pageId=664695865.

        Не требует авторизации
      operationId: KeyService_GetKeyWellKnownJwksJson
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetKeyWellKnownJwksJsonResponse"
        "400":
          description: Ошибка
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - key(public)
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /jwks/api/v1/system/status:
    get:
      summary: |-
        Метод получения статуса сервиса.
        Не требует авторизации
      operationId: SystemService_GetSystemStatus
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetSystemStatusResponse"
        "400":
          description: Ошибка
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - system(public)
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /jwks/internal/api/v1/key:
    post:
      summary: >-
        Метод сохранения публичного ключа.

        Используется сервисом KMS.

        Сценарий использования метода: https://confluence.rt.ru/pages/viewpage.action?pageId=664695357.

        Метод доступен для: service
      operationId: KeyService_PostKey
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKeyResponse"
        "400":
          description: Ошибка
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKeyResponse"
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostKeyResponse"
        default:
          description: Ошибки транспортного слоя
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/v1PostKeyRequest"
        required: true
      tags:
        - key(internal auth)
      security:
        - oauth2:
            - jwks:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  "/jwks/internal/api/v1/key/{id}":
    delete:
      summary: |-
        Метод удаления публичного ключа.
        Используется сервисом KMS.
        Метод доступен для: service
      operationId: KeyService_DeleteKey
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1DeleteKeyResponse"
        "400":
          description: Ошибка
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1DeleteKeyResponse"
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "404":
          description: Объект не найден
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1DeleteKeyResponse"
        default:
          description: Ошибки транспортного слоя
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      parameters:
        - name: id
          description: |-
            Идентификатор ключа, соответсвует kid.
            # Тип: Guid
          in: path
          required: true
          schema:
            type: string
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
      tags:
        - key(internal auth)
      security:
        - oauth2:
            - jwks:edit
          bearerHttp: []
components:
  schemas:
    KeyInfoPublicKey:
      type: object
      properties:
        use:
          type: string
          title: |-
            Вид использования.
            # Диапазон: 2..32
        kty:
          type: string
          title: |-
            Тип ключа.
            # Диапазон: 2..32
        kid:
          type: string
          title: |-
            Идентификатор.
            # Тип: Guid
        alg:
          type: string
          title: |-
            Алгоритм шифрования.
            # Диапазон: 2..32
        n:
          type: string
          title: Параметр Modulus
        e:
          type: string
          title: Параметр Exponent
        x5c:
          type: array
          items:
            type: string
          title: |-
            Цепочка сертификатов X.509.
            # Диапазон: 0..100
      title: Публичный ключ
      required:
        - use
        - kty
        - kid
        - n
        - e
    KeyInfoSavingError:
      type: object
      properties:
        keyAlreadyExists:
          title: Ключ с таким идентификатором уже существует
          allOf:
            - $ref: "#/components/schemas/SavingErrorKeyAlreadyExists"
      title: >-
        Ошибка сохранения.

        Эти проверки выполняются при работе с базой данных и сторонними сервисами
    SavingErrorKeyAlreadyExists:
      type: object
      title: |-
        Ключ с таким идентификатором уже существует.
        Причины:
        - В базе хранится запись с переданнм kid
    protobufAny:
      type: object
      properties:
        "@type":
          type: string
      additionalProperties: {}
      title: Произвольный JSON
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/protobufAny"
      title: Ошибка транспортного слоя
    v1DeleteKeyResponse:
      type: object
      properties:
        error:
          title: Ошибка
          allOf:
            - $ref: "#/components/schemas/v1DeleteKeyResponseError"
      title: Ответ на запрос удаления публичного ключа
    v1DeleteKeyResponseError:
      type: object
      properties:
        validation:
          title: Ошибка валидации
          allOf:
            - $ref: "#/components/schemas/v1ValidationError"
      title: Ошибка запроса удаления публичного ключа
    v1GetKeyWellKnownJwksJsonResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: "#/components/schemas/KeyInfoPublicKey"
          title: Список ключей
      title: Ответ на запрос на получение публичных ключей
    v1GetSystemStatusResponse:
      type: object
      title: Ответ на запрос проверки доступности сервиса
    v1PostKeyRequest:
      type: object
      properties:
        data:
          title: Ключ
          allOf:
            - $ref: "#/components/schemas/KeyInfoPublicKey"
      title: Запрос на сохранение публичного ключа
      required:
        - data
    v1PostKeyResponse:
      type: object
      properties:
        error:
          title: Ошибка
          allOf:
            - $ref: "#/components/schemas/v1PostKeyResponseError"
      title: Ответ на запрос на сохранение публичного ключа
    v1PostKeyResponseError:
      type: object
      properties:
        validation:
          title: Ошибки валидации
          allOf:
            - $ref: "#/components/schemas/v1ValidationError"
        saving:
          title: Ошибка сохранения
          allOf:
            - $ref: "#/components/schemas/KeyInfoSavingError"
      title: Ошибка
    v1ValidationError:
      type: object
      properties:
        path:
          type: string
          title: Путь к полю в формате наименования прото
        message:
          type: string
          title: Валидационное сообщение
      title: |-
        Ошибки валидации.
        Эти проверки выполняются до обращения в базу данных
      required:
        - path
        - message
  securitySchemes:
    bearerHttp:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth2-staging.k8s.key.rt.ru/oauth2/token
          scopes:
            jwks:edit: Предоставляет полный доступ в сервис jwks
            jwks:read: Предоставляет доступ на чтение данных из сервиса jwks
servers:
  - url: https://keyapis-staging.k8s.key.rt.ru
    description: staging
  - url: https://{feature}.k8s.key.rt.ru/
    description: https feature
    variables:
      feature:
        default: ""
        description: Feature name
  - url: http://{feature}.k8s.key.rt.ru/
    description: http feature
    variables:
      feature:
        default: ""
        description: Feature name
  - url: https://localhost:3001
    description: localhost
  - url: https://keyapis.key.rt.ru
    description: production
