You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/api/identity/v2_lookup.yaml

149 lines
5.4 KiB
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.
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"