matrix-spec/data/api/identity/v2_lookup.yaml

# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Lookup API"
  version: "2.0.0"
host: localhost:8090
schemes:
  - https
basePath: /_matrix/identity/v2
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/hash_details":
    get:
      summary: Gets hash function information from the server.
      description: |-
        Gets parameters for hashing identifiers from the server. This can include
        any of the algorithms defined in this specification.        
      operationId: getHashDetails
      security:
        - accessToken: []
      parameters: []
      responses:
        200:
          description: The hash function information.
          examples:
            application/json: {
              "lookup_pepper": "matrixrocks",
              "algorithms": ["none", "sha256"]
            }
          schema:
            type: object
            properties:
              lookup_pepper:
                type: string
                description: |-
                  The pepper the client MUST use in hashing identifiers, and MUST
                  supply to the `/lookup` endpoint when performing lookups.

                  Servers SHOULD rotate this string often.                  
              algorithms:
                type: array
                items:
                  type: string
                description: |-
                                    The algorithms the server supports. Must contain at least `sha256`.
            required: ['lookup_pepper', 'algorithms']
  "/lookup":
    post:
      summary: Look up Matrix User IDs for a set of 3PIDs.
      description: |-
        Looks up the set of Matrix User IDs which have bound the 3PIDs given, if
        bindings are available. Note that the format of the addresses is defined
        later in this specification.        
      operationId: lookupUsersV2
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              algorithm:
                type: string
                description: |-
                  The algorithm the client is using to encode the `addresses`. This
                  should be one of the available options from `/hash_details`.                  
                example: "sha256"
              pepper:
                type: string
                description: |-
                  The pepper from `/hash_details`. This is required even when the
                  `algorithm` does not make use of it.                  
                example: "matrixrocks"
              addresses:
                type: array
                items:
                  type: string
                description: |-
                  The addresses to look up. The format of the entries here depend on
                  the `algorithm` used. Note that queries which have been incorrectly
                  hashed or formatted will lead to no matches.

                  Note that addresses are case sensitive: review the
                  [3PID Types](/appendices#pid-types) to verify the intended case an
                  identifier should be prior to submission/hashing.                  
                example: [
                  "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
                  "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
                ]
            required: ['algorithm', 'pepper', 'addresses']
      responses:
        200:
          description:
            The associations for any matched `addresses`.
          examples:
            application/json: {
              "mappings": {
                "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
              }
            }
          schema:
            type: object
            properties:
              mappings:
                type: object
                description: |-
                  Any applicable mappings of `addresses` to Matrix User IDs. Addresses
                  which do not have associations will not be included, which can make
                  this property be an empty object.                  
                title: AssociatedMappings
                additionalProperties:
                  type: string
            required: ['mappings']
        400:
          description:
            The client's request was invalid in some way. One possible problem could
            be the `pepper` being invalid after the server has rotated it - this is
            presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make
            a call to `/hash_details` to get a new pepper in this scenario, being
            careful to avoid retry loops.

            `M_INVALID_PARAM` can also be returned to indicate the client supplied
            an `algorithm` that is unknown to the server.
          examples:
            application/json: {
              "errcode": "M_INVALID_PEPPER",
              "error": "Unknown or invalid pepper - has it been rotated?"
            }
          schema:
            $ref: "../client-server/definitions/errors/error.yaml"