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/data/api/identity/v2_lookup.yaml

171 lines
6.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.
openapi: 3.1.0
info:
title: Matrix Identity Service Lookup API
version: 2.0.0
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:
- accessTokenQuery: []
- accessTokenBearer: []
responses:
"200":
description: The hash function information.
content:
application/json:
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
examples:
response:
value: {
"lookup_pepper": "matrixrocks",
"algorithms": [
"none",
"sha256"
]
}
/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:
- accessTokenQuery: []
- accessTokenBearer: []
requestBody:
content:
application/json:
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#3pid-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`.
content:
application/json:
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
examples:
response:
value: {
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
"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.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_PEPPER",
"error": "Unknown or invalid pepper - has it been rotated?"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer