matrix-spec/data/api/client-server/whoami.yaml

# Copyright 2017 Travis Ralston
#
# 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 Account Identification API
  version: 1.0.0
paths:
  /account/whoami:
    get:
      summary: Gets information about the owner of an access token.
      description: |-
        Gets information about the owner of a given access token.

        Note that, as with the rest of the Client-Server API,
        Application Services may masquerade as users within their
        namespace by giving a `user_id` query parameter. In this
        situation, the server should verify that the given `user_id`
        is registered by the appservice, and return it in the response
        body.
      operationId: getTokenOwner
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      responses:
        "200":
          description: The token belongs to a known user.
          content:
            application/json:
              schema:
                type: object
                required:
                  - user_id
                properties:
                  user_id:
                    type: string
                    description: The user ID that owns the access token.
                  device_id:
                    x-addedInMatrixVersion: "1.1"
                    type: string
                    description: |-
                      Device ID associated with the access token. If no device
                      is associated with the access token (such as in the case
                      of application services) then this field can be omitted.
                      Otherwise this is required.
                  is_guest:
                    x-addedInMatrixVersion: "1.2"
                    type: boolean
                    description: |-
                      When `true`, the user is a [Guest User](#guest-access). When
                      not present or `false`, the user is presumed to be a non-guest
                      user.
              examples:
                response:
                  value: {
                    "user_id": "@joe:example.org",
                    "device_id": "ABC1234"
                  }
        "401":
          description: The token is not recognised
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_UNKNOWN_TOKEN",
                    "error": "Unrecognised access token."
                  }
        "403":
          description: The appservice cannot masquerade as the user or has not registered
            them.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
              examples:
                response:
                  value: {
                    "errcode": "M_FORBIDDEN",
                    "error": "Application service has not registered this user."
                  }
        "429":
          description: This request was rate-limited.
          content:
            application/json:
              schema:
                $ref: definitions/errors/rate_limited.yaml
      tags:
        - Session management
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer