matrix-spec-proposals/api/client-server/openid.yaml

# 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.
swagger: '2.0'
info:
  title: "Matrix Client-Server OpenID API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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
          type: string
          name: userId
          description: |-
            The user to request and OpenID token for. Should be the user who
            is authenticated for the request.
          required: true
          x-example: "@alice:example.com"
        - in: body
          name: body
          description: An empty object. Reserved for future expansion.
          required: true
          schema:
            type: object
            example: {}
      responses:
        200:
          description: |-
            OpenID token information. This response is nearly compatible with the
            response documented in the `OpenID 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.
          examples:
            application/json: {
              "access_token": "SomeT0kenHere",
              "token_type": "Bearer",
              "matrix_server_name": "example.com",
              "expires_in": 3600,
            }
          schema:
            type: object
            properties:
              access_token:
                type: string
                description: |-
                  An access token the consumer may use to verify the identity of
                  the person who generated the token. This is given to the federation
                  API ``GET /openid/userinfo``.
              token_type:
                type: string
                description: The string ``Bearer``.
              matrix_server_name:
                type: string
                description: |-
                  The homeserver domain the consumer should use when attempting to
                  verify the user's identity.
              expires_in:
                type: int
                description: |-
                  The number of seconds before this token expires and a new one must
                  be generated.
            required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
        429:
          description: This request was rate-limited.
          schema:
            "$ref": "definitions/errors/rate_limited.yaml"
      tags:
        - OpenID