# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
  title: Matrix Client-Server OpenID API
  version: 1.0.0
paths:
  "/user/{userId}/openid/request_token":
    post:
      summary: Get an OpenID token object to verify the requester's identity.
      description: |-
        Gets an OpenID token object that the requester may supply to another
        service to verify their identity in Matrix. The generated token is only
        valid for exchanging for user information from the federation API for
        OpenID.

        The access token generated is only valid for the OpenID API. It cannot
        be used to request another OpenID access token or call `/sync`, for
        example.
      operationId: requestOpenIdToken
      security:
        - accessToken: []
      parameters:
        - in: path
          name: userId
          description: |-
            The user to request an OpenID token for. Should be the user who
            is authenticated for the request.
          required: true
          example: "@alice:example.com"
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {}
        description: An empty object. Reserved for future expansion.
        required: true
      responses:
        "200":
          description: |-
            OpenID token information. This response is nearly compatible with the
            response documented in the
            [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse)
            with the only difference being the lack of an `id_token`. Instead,
            the Matrix homeserver's name is provided.
          content:
            application/json:
              schema:
                $ref: definitions/openid_token.yaml
              examples:
                response:
                  value: {
                    "access_token": "SomeT0kenHere",
                    "token_type": "Bearer",
                    "matrix_server_name": "example.com",
                    "expires_in": 3600
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - OpenID
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    $ref: definitions/security.yaml