archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix indentation and schema references in the identity service spec

Browse Source
pull/977/head
Travis Ralston 6 years ago
parent 4abd618147
commit dafea96621
9 changed files with 162 additions and 92 deletions
Show Stats Download Patch File Download Diff File

69
api/identity/associations.yaml
Unescape Escape View File

@ -46,10 +46,10 @@ paths:
description: Validation information for the session. description: Validation information for the session.
examples: examples:
application/json: { application/json: {
"medium": "email", "medium": "email",
"validated_at": 1457622739026, "validated_at": 1457622739026,
"address": "louise@bobs.burgers" "address": "louise@bobs.burgers"
} }
schema: schema:
type: object type: object
properties: properties:
@ -72,16 +72,20 @@ paths:
``errcode`` will be ``M_SESSION_EXPIRED``. ``errcode`` will be ``M_SESSION_EXPIRED``.
examples: examples:
application/json: { application/json: {
"errcode": "M_SESSION_NOT_VALIDATED", "errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed" "error": "This validation session has not yet been completed"
} }
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404: 404:
description: The Session ID or client secret were not found description: The Session ID or client secret were not found
examples: examples:
application/json: { application/json: {
"errcode": "M_NO_VALID_SESSION", "errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret" "error": "No valid session was found matching that sid and client secret"
} }
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/bind": "/bind":
post: post:
summary: Publish an association between a session and a Matrix user ID. summary: Publish an association between a session and a Matrix user ID.
@ -102,10 +106,10 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"sid": "1234", "sid": "1234",
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org" "mxid": "@ears:matrix.org"
} }
properties: properties:
sid: sid:
type: string type: string
@ -122,19 +126,19 @@ paths:
description: The association was published. description: The association was published.
examples: examples:
application/json: { application/json: {
"address": "louise@bobs.burgers", "address": "louise@bobs.burgers",
"medium": "email", "medium": "email",
"mxid": "@ears:matrix.org", "mxid": "@ears:matrix.org",
"not_before": 1428825849161, "not_before": 1428825849161,
"not_after": 4582425849161, "not_after": 4582425849161,
"ts": 1428825849161, "ts": 1428825849161,
"signatures": { "signatures": {
"matrix.org": { "matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
} }
} }
}
schema: schema:
type: object type: object
properties: properties:
@ -159,6 +163,7 @@ paths:
signatures: signatures:
type: object type: object
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
$ref: "../../schemas/server-signatures.yaml"
required: required:
- address - address
- medium - medium
@ -176,13 +181,17 @@ paths:
``errcode`` will be ``M_SESSION_EXPIRED``. ``errcode`` will be ``M_SESSION_EXPIRED``.
examples: examples:
application/json: { application/json: {
"errcode": "M_SESSION_NOT_VALIDATED", "errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed" "error": "This validation session has not yet been completed"
} }
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404: 404:
description: The Session ID or client secret were not found description: The Session ID or client secret were not found
examples: examples:
application/json: { application/json: {
"errcode": "M_NO_VALID_SESSION", "errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret" "error": "No valid session was found matching that sid and client secret"
} }
schema:
$ref: "../client-server/definitions/errors/error.yaml"

31
api/identity/email_associations.yaml
Unescape Escape View File

@ -51,10 +51,10 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"email": "foo@example.com", "email": "foo@example.com",
"send_attempt": 1 "send_attempt": 1
} }
properties: properties:
client_secret: client_secret:
type: string type: string
@ -85,8 +85,8 @@ paths:
Session created. Session created.
examples: examples:
application/json: { application/json: {
"sid": "1234" "sid": "1234"
} }
schema: schema:
type: object type: object
properties: properties:
@ -100,6 +100,13 @@ paths:
- ``M_INVALID_EMAIL``: The email address provided was invalid. - ``M_INVALID_EMAIL``: The email address provided was invalid.
- ``M_EMAIL_SEND_ERROR``: The validation email could not be sent. - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
examples:
application/json: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/email/submitToken": "/validate/email/submitToken":
post: post:
summary: Validate ownership of an email address. summary: Validate ownership of an email address.
@ -123,10 +130,10 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"sid": "1234", "sid": "1234",
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"token": "atoken" "token": "atoken"
} }
properties: properties:
sid: sid:
type: string type: string
@ -144,8 +151,8 @@ paths:
The success of the validation. The success of the validation.
examples: examples:
application/json: { application/json: {
"success": true "success": true
} }
schema: schema:
type: object type: object
properties: properties:

6
api/identity/invitation_signing.yaml
Unescape Escape View File

@ -68,6 +68,7 @@ paths:
signatures: signatures:
type: object type: object
description: The signature of the mxid, sender, and token. description: The signature of the mxid, sender, and token.
$ref: "../../schemas/server-signatures.yaml"
token: token:
type: string type: string
description: The token for the invitation. description: The token for the invitation.
@ -85,7 +86,10 @@ paths:
} }
404: 404:
description: Token was not found. description: Token was not found.
example: { examples:
application/json: {
"errcode": "M_UNRECOGNIZED", "errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token" "error": "Didn't recognize token"
} }
schema:
$ref: "../client-server/definitions/errors/error.yaml"

35
api/identity/lookup.yaml
Unescape Escape View File

@ -49,19 +49,18 @@ paths:
The association for that 3pid, or the empty object if no association is known. The association for that 3pid, or the empty object if no association is known.
examples: examples:
application/json: { application/json: {
"address": "louise@bobs.burgers", "address": "louise@bobs.burgers",
"medium": "email", "medium": "email",
"mxid": "@ears:matrix.org", "mxid": "@ears:matrix.org",
"not_before": 1428825849161, "not_before": 1428825849161,
"not_after": 4582425849161, "not_after": 4582425849161,
"ts": 1428825849161, "ts": 1428825849161,
"signatures": {
"signatures": { "matrix.org": {
"matrix.org": { "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
} }
} }
}
schema: schema:
type: object type: object
properties: properties:
@ -86,6 +85,7 @@ paths:
signatures: signatures:
type: object type: object
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
$ref: "../../schemas/server-signatures.yaml"
required: required:
- address - address
- medium - medium
@ -118,9 +118,11 @@ paths:
items: items:
type: array type: array
title: 3PID mappings title: 3PID mappings
minItems: 2
maxItems: 2
items: items:
type: string - type: 3PID Medium
title: 3PID medium or address - type: 3PID Address
description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position. description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
required: required:
- "threepids" - "threepids"
@ -142,9 +144,12 @@ paths:
items: items:
type: array type: array
title: 3PID mappings title: 3PID mappings
minItems: 3
maxItems: 3
items: items:
type: string - type: 3PID Medium
title: 3PID medium or address or the Matrix ID - type: 3PID Address
- type: Matrix User ID
description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position. description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
required: required:
- "threepids" - "threepids"

33
api/identity/phone_associations.yaml
Unescape Escape View File

@ -51,11 +51,11 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"country": "GB", "country": "GB",
"phone_number": "07700900001", "phone_number": "07700900001",
"send_attempt": 1 "send_attempt": 1
} }
properties: properties:
client_secret: client_secret:
type: string type: string
@ -91,8 +91,8 @@ paths:
Session created. Session created.
examples: examples:
application/json: { application/json: {
"sid": "1234" "sid": "1234"
} }
schema: schema:
type: object type: object
properties: properties:
@ -106,6 +106,13 @@ paths:
- ``M_INVALID_ADDRESS``: The phone number provided was invalid. - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
- ``M_SEND_ERROR``: The validation SMS could not be sent. - ``M_SEND_ERROR``: The validation SMS could not be sent.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/msisdn/submitToken": "/validate/msisdn/submitToken":
post: post:
summary: Validate ownership of a phone number. summary: Validate ownership of a phone number.
@ -129,10 +136,10 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"sid": "1234", "sid": "1234",
"client_secret": "monkeys_are_GREAT", "client_secret": "monkeys_are_GREAT",
"token": "atoken" "token": "atoken"
} }
properties: properties:
sid: sid:
type: string type: string
@ -150,8 +157,8 @@ paths:
The success of the validation. The success of the validation.
examples: examples:
application/json: { application/json: {
"success": true "success": true
} }
schema: schema:
type: object type: object
properties: properties:

20
api/identity/pubkey.yaml
Unescape Escape View File

@ -45,13 +45,25 @@ paths:
The public key exists. The public key exists.
examples: examples:
application/json: { application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
} }
schema: schema:
type: object type: object
properties: properties:
public_key: public_key:
type: string type: string
description: Unpadded Base64 encoded public key.
required: ['public_key']
404:
description:
The public key was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/pubkey/isvalid": "/pubkey/isvalid":
get: get:
summary: Check whether a long-term public key is valid. summary: Check whether a long-term public key is valid.
@ -72,8 +84,8 @@ paths:
The validity of the public key. The validity of the public key.
examples: examples:
application/json: { application/json: {
"valid": true "valid": true
} }
schema: schema:
type: object type: object
properties: properties:

34
api/identity/store_invite.yaml
Unescape Escape View File

@ -54,11 +54,11 @@ paths:
schema: schema:
type: object type: object
example: { example: {
"medium": "email", "medium": "email",
"address": "foo@bar.baz", "address": "foo@bar.baz",
"room_id": "!something:example.tld", "room_id": "!something:example.tld",
"sender": "@bob:example.com" "sender": "@bob:example.com"
} }
properties: properties:
medium: medium:
type: string type: string
@ -93,13 +93,13 @@ paths:
required: ['token', 'public_keys', 'display_name'] required: ['token', 'public_keys', 'display_name']
example: example:
application/json: { application/json: {
"token": "sometoken", "token": "sometoken",
"public_keys": [ "public_keys": [
"serverpublickey", "serverpublickey",
"ephemeralpublickey" "ephemeralpublickey"
], ],
"display_name": "f...@b..." "display_name": "f...@b..."
} }
400: 400:
description: | description: |
An error has occured. An error has occured.
@ -109,7 +109,9 @@ paths:
error code will be ``M_UNRECOGNIZED``. error code will be ``M_UNRECOGNIZED``.
examples: examples:
application/json: { application/json: {
"errcode": "M_THREEPID_IN_USE", "errcode": "M_THREEPID_IN_USE",
"error": "Binding already known", "error": "Binding already known",
"mxid": mxid "mxid": mxid
} }
schema:
$ref: "../client-server/definitions/errors/error.yaml"

24
schemas/server-signatures.yaml
Unescape Escape View File

@ -0,0 +1,24 @@
# 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.
type: object
example: {
"example.com": {
"ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
}
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string

2
specification/identity_service_api.rst
Unescape Escape View File

@ -23,7 +23,7 @@ user identifiers. From time to time, it is useful to refer to users by other
number. This identity service specification describes how mappings between number. This identity service specification describes how mappings between
third-party identifiers and Matrix user identifiers can be established, third-party identifiers and Matrix user identifiers can be established,
validated, and used. This description technically may apply to any 3pid, but in validated, and used. This description technically may apply to any 3pid, but in
practice has only been applied specifically to email addresses. practice has only been applied specifically to email addresses and phone numbers.
.. contents:: Table of Contents .. contents:: Table of Contents
.. sectnum:: .. sectnum::

Write Preview
Loading…
Cancel
Save