wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Upgrade Swagger data to OpenAPI 3.1 (#1310)

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2023-06-07 14:16:29 +02:00 • committed by GitHub
parent c64a616d54
commit 45b6aaf07a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
118 changed files with 15064 additions and 12727 deletions
Download patch file Download diff file Expand all files Collapse all files

512
data/api/identity/v2_associations.yaml
View file

@ -12,102 +12,108 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Establishing Associations 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
title: Matrix Identity Service Establishing Associations API
version: 2.0.0
paths:
"/3pid/getValidated3pid":
/3pid/getValidated3pid:
get:
summary: Check whether ownership of a 3pid was validated.
description: |-
Determines if a given 3pid has been validated by a user.
description: Determines if a given 3pid has been validated by a user.
operationId: getValidated3pidV2
security:
- accessToken: []
parameters:
- in: query
type: string
name: sid
description: The Session ID generated by the `requestToken` call.
required: true
x-example: 1234
example: 1234
schema:
type: string
- in: query
type: string
name: client_secret
description: The client secret passed to the `requestToken` call.
required: true
x-example: monkeys_are_GREAT
responses:
200:
description: Validation information for the session.
examples:
application/json: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
example: monkeys_are_GREAT
schema:
type: object
properties:
medium:
type: string
description: The medium type of the 3pid.
address:
type: string
description: The address of the 3pid being looked up.
validated_at:
type: integer
format: int64
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
type: string
responses:
"200":
description: Validation information for the session.
content:
application/json:
schema:
type: object
properties:
medium:
type: string
description: The medium type of the 3pid.
address:
type: string
description: The address of the 3pid being looked up.
validated_at:
type: integer
format: int64
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required:
- medium
- address
- validated_at
examples:
response:
value: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
"400":
description: |-
The session has not been validated.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found.
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/bind":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The Session ID or client secret were not found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
/3pid/bind:
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
@ -123,119 +129,136 @@ paths:
operationId: bindV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required: ["sid", "client_secret", "mxid"]
responses:
200:
description: The association was published.
examples:
application/json: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
}
schema:
type: object
properties:
address:
type: string
description: The 3pid address of the user being looked up.
medium:
type: string
description: The medium type of the 3pid.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
format: int64
description: A unix timestamp before which the association is not known to be valid.
not_after:
type: integer
format: int64
description: A unix timestamp after which the association is not known to be valid.
ts:
type: integer
format: int64
description: The unix timestamp at which the association was verified.
signatures:
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required:
- sid
- client_secret
- mxid
responses:
"200":
description: The association was published.
content:
application/json:
schema:
type: object
description: |-
The signatures of the verifying identity servers which show that the
association should be trusted, if you trust the verifying identity
services.
allOf:
- $ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
400:
properties:
address:
type: string
description: The 3pid address of the user being looked up.
medium:
type: string
description: The medium type of the 3pid.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
format: int64
description: A unix timestamp before which the association is not known to be
valid.
not_after:
type: integer
format: int64
description: A unix timestamp after which the association is not known to be
valid.
ts:
type: integer
format: int64
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: |-
The signatures of the verifying identity servers which show that the
association should be trusted, if you trust the verifying identity
services.
allOf:
- $ref: ../../schemas/server-signatures.yaml
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
examples:
response:
value: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
"400":
description: |-
The association was not published.
If the session has not been validated, then `errcode` will be
`M_SESSION_NOT_VALIDATED`. If the session has timed out, then
`errcode` will be `M_SESSION_EXPIRED`.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/unbind":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The Session ID or client secret were not found
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
/3pid/unbind:
post:
summary: Remove an association between a session and a Matrix user ID.
description: |-
@ -257,65 +280,67 @@ paths:
operationId: unbindV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
}
}
}
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required: ['medium', 'address']
required: ["threepid", "mxid"]
properties:
sid:
type: string
description: The Session ID generated by the `requestToken` call.
client_secret:
type: string
description: The client secret passed to the `requestToken` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using `sid` and `client_secret` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the [3PID Types](/appendices/#3pid-types) Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required:
- medium
- address
required:
- threepid
- mxid
responses:
200:
"200":
description: The association was successfully removed.
examples:
application/json: {}
schema:
type: object
400:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"400":
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
404:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
403:
"403":
description: |-
The credentials supplied to authenticate the request were invalid.
This may also be returned if the identity server does not support
@ -324,15 +349,38 @@ paths:
Another common error code is `M_TERMS_NOT_SIGNED` where the user
needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
501:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
"404":
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
"501":
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

186
data/api/identity/v2_auth.yaml
View file

@ -11,22 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Authentication 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
title: Matrix Identity Service Authentication API
version: 2.0.0
paths:
"/account/register":
/account/register:
post:
summary: Exchanges an OpenID token for an access token.
description: |-
@ -34,64 +24,74 @@ paths:
access the identity server. The request body is the same as the values
returned by `/openid/request_token` in the Client-Server API.
operationId: registerAccount
parameters:
- in: body
name: body
schema:
$ref: "../client-server/definitions/openid_token.yaml"
requestBody:
content:
application/json:
schema:
$ref: ../client-server/definitions/openid_token.yaml
responses:
200:
"200":
description: |-
A token which can be used to authenticate future requests to the
identity server.
examples:
application/json: {
"token": "abc123_OpaqueString"
}
schema:
type: object
properties:
token:
type: string
description: |-
An opaque string representing the token to authenticate future
requests to the identity server with.
required: ['token']
"/account":
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: |-
An opaque string representing the token to authenticate future
requests to the identity server with.
required:
- token
examples:
response:
value: {
"token": "abc123_OpaqueString"
}
/account:
get:
summary: Gets account holder information for a given token.
description: |-
Gets information about what user owns the access token used in the request.
description: Gets information about what user owns the access token used in the
request.
operationId: getAccount
security:
- accessToken: []
parameters: []
responses:
200:
"200":
description: The token holder's information.
examples:
application/json: {
"user_id": "@alice:example.org"
}
schema:
type: object
properties:
user_id:
type: string
description: The user ID which registered the token.
required: ['user_id']
403:
content:
application/json:
schema:
type: object
properties:
user_id:
type: string
description: The user ID which registered the token.
required:
- user_id
examples:
response:
value: {
"user_id": "@alice:example.org"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/account/logout":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
/account/logout:
post:
summary: Logs out an access token, rendering it unusable.
description: |-
@ -100,32 +100,54 @@ paths:
operationId: logout
security:
- accessToken: []
parameters: []
responses:
200:
"200":
description: The token was successfully logged out.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The token is not registered or is otherwise unknown to the server.
examples:
application/json: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
type: object
examples:
response:
value: {}
"401":
description: The token is not registered or is otherwise unknown to the server.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

239
data/api/identity/v2_email_associations.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Email Associations 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
title: Matrix Identity Service Email Associations API
version: 2.0.0
paths:
"/validate/email/requestToken":
/validate/email/requestToken:
post:
summary: Request a token for validating an email address.
description: |-
@ -51,41 +41,49 @@ paths:
operationId: emailRequestTokenV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
$ref: "definitions/request_email_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_email_validation.yaml
responses:
200:
"200":
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
content:
application/json:
schema:
$ref: definitions/sid.yaml
"400":
description: |
An error occurred. Some possible errors are:
- `M_INVALID_EMAIL`: The email address provided was invalid.
- `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"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/email/submitToken":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
/validate/email/submitToken:
post:
summary: Validate ownership of an email address.
description: |-
@ -110,53 +108,63 @@ paths:
operationId: emailSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and emailed to the user.
required: ["sid", "client_secret", "token"]
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and emailed to the
user.
required:
- sid
- client_secret
- token
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
403:
"200":
description: The success of the validation.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required:
- success
examples:
response:
value: {
"success": true
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
get:
summary: Validate ownership of an email address.
description: |-
@ -175,42 +183,63 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the `requestToken` call.
x-example: 1234
example: 1234
schema:
type: string
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
example: monkeys_are_GREAT
schema:
type: string
- in: query
type: string
name: token
required: true
description: The token generated by the `requestToken` call and emailed to the user.
x-example: atoken
description: The token generated by the `requestToken` call and emailed to the
user.
example: atoken
schema:
type: string
responses:
200:
"200":
description: Email address is validated.
"3xx":
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"3XX":
description: |-
Email address is validated, and the `next_link` parameter was
provided to the `requestToken` call. The user must be redirected
to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"4XX":
description: Validation failed.
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

184
data/api/identity/v2_invitation_signing.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Ephemeral Invitation Signing 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
title: Matrix Identity Service Ephemeral Invitation Signing API
version: 2.0.0
paths:
"/sign-ed25519":
/sign-ed25519:
post:
summary: Sign invitation details
description: |-
@ -38,76 +28,108 @@ paths:
operationId: blindlySignStuffV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The token from the call to `store-invite`.
private_key:
type: string
description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
required: ["mxid", "token", "private_key"]
requestBody:
content:
application/json:
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The token from the call to `store-invite`.
private_key:
type: string
description: The private key, encoded as [Unpadded
base64](/appendices/#unpadded-base64).
required:
- mxid
- token
- private_key
responses:
200:
"200":
description: The signed JSON of the mxid, sender, and token.
schema:
type: object
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
content:
application/json:
schema:
type: object
description: The signature of the mxid, sender, and token.
allOf:
- $ref: "../../schemas/server-signatures.yaml"
token:
type: string
description: The token for the invitation.
required: ['mxid', 'sender', 'signatures', 'token']
examples:
application/json: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
404:
description: The token was not found.
examples:
application/json: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
type: object
description: The signature of the mxid, sender, and token.
allOf:
- $ref: ../../schemas/server-signatures.yaml
token:
type: string
description: The token for the invitation.
required:
- mxid
- sender
- signatures
- token
examples:
response:
value: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"404":
description: The token was not found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

231
data/api/identity/v2_lookup.yaml
View file

@ -15,22 +15,12 @@
# 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'
openapi: 3.1.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
title: Matrix Identity Service Lookup API
version: 2.0.0
paths:
"/hash_details":
/hash_details:
get:
summary: Gets hash function information from the server.
description: |-
@ -39,33 +29,39 @@ paths:
operationId: getHashDetails
security:
- accessToken: []
parameters: []
responses:
200:
"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.
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']
"/lookup":
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: |-
@ -75,78 +71,95 @@ paths:
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:
requestBody:
content:
application/json:
schema:
type: object
properties:
algorithm:
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.
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']
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`.
examples:
application/json: {
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
schema:
type: object
properties:
mappings:
"200":
description: The associations for any matched `addresses`.
content:
application/json:
schema:
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"
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:
$ref: definitions/security.yaml

236
data/api/identity/v2_phone_associations.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Phone Number Associations 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
title: Matrix Identity Service Phone Number Associations API
version: 2.0.0
paths:
"/validate/msisdn/requestToken":
/validate/msisdn/requestToken:
post:
summary: Request a token for validating a phone number.
description: |-
@ -51,17 +41,19 @@ paths:
operationId: msisdnRequestTokenV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
$ref: "definitions/request_msisdn_validation.yaml"
requestBody:
content:
application/json:
schema:
$ref: definitions/request_msisdn_validation.yaml
responses:
200:
"200":
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
content:
application/json:
schema:
$ref: definitions/sid.yaml
"400":
description: |
An error occurred. Some possible errors are:
@ -69,25 +61,31 @@ paths:
- `M_SEND_ERROR`: The validation SMS could not be sent.
- `M_DESTINATION_REJECTED`: The identity server cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/msisdn/submitToken":
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
/validate/msisdn/submitToken:
post:
summary: Validate ownership of a phone number.
description: |-
@ -112,53 +110,63 @@ paths:
operationId: msisdnSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and sent to the user.
required: ["sid", "client_secret", "token"]
requestBody:
content:
application/json:
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the `requestToken` call.
client_secret:
type: string
description: The client secret that was supplied to the `requestToken` call.
token:
type: string
description: The token generated by the `requestToken` call and sent to the
user.
required:
- sid
- client_secret
- token
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
403:
"200":
description: The success of the validation.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required:
- success
examples:
response:
value: {
"success": true
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
get:
summary: Validate ownership of a phone number.
description: |-
@ -177,42 +185,62 @@ paths:
- accessToken: []
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the `requestToken` call.
x-example: 1234
example: 1234
schema:
type: string
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the `requestToken` call.
x-example: monkeys_are_GREAT
example: monkeys_are_GREAT
schema:
type: string
- in: query
type: string
name: token
required: true
description: The token generated by the `requestToken` call and sent to the user.
x-example: atoken
example: atoken
schema:
type: string
responses:
200:
"200":
description: Phone number is validated.
"3xx":
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
"3XX":
description: |-
Phone number address is validated, and the `next_link` parameter
was provided to the `requestToken` call. The user must be
redirected to the URL provided by the `next_link` parameter.
"4xx":
description:
Validation failed.
403:
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"4XX":
description: Validation failed.
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

40
data/api/identity/v2_ping.yaml
View file

@ -13,19 +13,12 @@
# 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"
openapi: 3.1.0
info:
title: "Matrix Identity Service Ping API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
title: Matrix Identity Service Ping API
version: 2.0.0
paths:
"/v2":
/v2:
get:
summary: Checks that an identity server is available at this API endpoint.
description: |-
@ -38,9 +31,24 @@ paths:
by entities acting as a client for the identity server.
operationId: pingV2
responses:
200:
"200":
description: An identity server is ready to serve requests.
examples:
application/json: {}
schema:
type: object
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity

172
data/api/identity/v2_pubkey.yaml
View file

@ -12,61 +12,58 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Public Key API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
title: Matrix Identity Service Public Key API
version: 2.0.0
paths:
"/pubkey/{keyId}":
get:
summary: Get a public key.
description: |-
Get the public key for the passed key ID.
description: Get the public key for the passed key ID.
operationId: getPubKeyV2
parameters:
- in: path
type: string
name: keyId
required: true
description: |-
The ID of the key. This should take the form algorithm:identifier
where algorithm identifies the signing algorithm, and the identifier
is an opaque string.
x-example: "ed25519:0"
example: ed25519:0
schema:
type: string
responses:
200:
description:
The public key exists.
examples:
application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
schema:
type: object
properties:
public_key:
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":
"200":
description: The public key exists.
content:
application/json:
schema:
type: object
properties:
public_key:
type: string
description: Unpadded Base64 encoded public key.
required:
- public_key
examples:
response:
value: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
"404":
description: The public key was not found.
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
/pubkey/isvalid:
get:
summary: Check whether a long-term public key is valid.
description: |-
@ -75,53 +72,70 @@ paths:
operationId: isPubKeyValidV2
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
description: The unpadded base64-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
"/pubkey/ephemeral/isvalid":
type: string
responses:
"200":
description: The validity of the public key.
content:
application/json:
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required:
- valid
examples:
response:
value: {
"valid": true
}
/pubkey/ephemeral/isvalid:
get:
summary: Check whether a short-term public key is valid.
description: |-
Check whether a short-term public key is valid.
description: Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValidV2
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
description: The unpadded base64-encoded public key to check.
example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
type: string
responses:
"200":
description: The validity of the public key.
content:
application/json:
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required:
- valid
examples:
response:
value: {
"valid": true
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2

308
data/api/identity/v2_store_invite.yaml
View file

@ -12,22 +12,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Store Invitations 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
title: Matrix Identity Service Store Invitations API
version: 2.0.0
paths:
"/store-invite":
/store-invite:
post:
summary: Store pending invitations to a user's 3pid.
description: |-
@ -62,142 +52,176 @@ paths:
operationId: storeInviteV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
medium:
type: string
description: The literal string `email`.
example: "email"
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:example.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the `m.room.avatar` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The `join_rule` for the room to which the user is invited. This should
be retrieved from the `m.room.join_rules` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the `m.room.name` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: "Bob Smith"
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the invite.
example: "mxc://example.org/an0th3rM3dia"
room_type:
type: string
description: |-
The `type` from the `m.room.create` event's `content`. If the create event doesn't
have a specified `type`, this field is not included.
example: "m.space"
required: ["medium", "address", "room_id", "sender"]
requestBody:
content:
application/json:
schema:
type: object
properties:
medium:
type: string
description: The literal string `email`.
example: email
address:
type: string
description: The email address of the invited user.
example: foo@example.com
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the `m.room.canonical_alias`
state event.
example: "#somewhere:example.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the `m.room.avatar` state event.
example: mxc://example.org/s0meM3dia
room_join_rules:
type: string
description: |-
The `join_rule` for the room to which the user is invited. This should
be retrieved from the `m.room.join_rules` state event.
example: public
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the `m.room.name` state event.
example: Bob's Emporium of Messages
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: Bob Smith
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the
invite.
example: mxc://example.org/an0th3rM3dia
room_type:
type: string
description: |-
The `type` from the `m.room.create` event's `content`. If the create event doesn't
have a specified `type`, this field is not included.
example: m.space
required:
- medium
- address
- room_id
- sender
responses:
200:
"200":
description: The invitation was stored.
schema:
type: object
properties:
token:
type: string
description: |
The generated token. Must be a string consisting of the
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
description: |
A list of [server's long-term public key, generated ephemeral
public key].
items:
type: object
title: PublicKey
properties:
public_key:
type: string
description: |
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
key_validity_url:
type: string
description: |
The URI of an endpoint where the validity of this key can be checked
by passing it as a `public_key` query parameter. See
[key management](/identity-service-api/#key-management).
required: ['public_key', 'key_validity_url']
display_name:
type: string
description: The generated (redacted) display name.
required: ['token', 'public_keys', 'display_name']
examples:
application/json: {
"token": "sometoken",
"public_keys": [
{
"public_key": "serverPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
},
{
"public_key": "ephemeralPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
}
],
"display_name": "f...@b..."
}
400:
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: |
The generated token. Must be a string consisting of the
characters `[0-9a-zA-Z.=_-]`. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
description: |
A list of [server's long-term public key, generated ephemeral
public key].
items:
type: object
title: PublicKey
properties:
public_key:
type: string
description: |
The public key, encoded using [unpadded Base64](/appendices/#unpadded-base64).
key_validity_url:
type: string
description: |
The URI of an endpoint where the validity of this key can be checked
by passing it as a `public_key` query parameter. See
[key management](/identity-service-api/#key-management).
required:
- public_key
- key_validity_url
display_name:
type: string
description: The generated (redacted) display name.
required:
- token
- public_keys
- display_name
examples:
response:
value: {
"token": "sometoken",
"public_keys": [
{
"public_key": "serverPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/isvalid"
},
{
"public_key": "ephemeralPublicKeyBase64",
"key_validity_url": "https://example.com/_matrix/identity/v2/pubkey/ephemeral/isvalid"
}
],
"display_name": "f...@b..."
}
"400":
description: |
An error has occurred.
If the 3pid is already bound to a Matrix user ID, the error code
will be `M_THREEPID_IN_USE`. If the medium is unsupported, the
error code will be `M_UNRECOGNIZED`.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
"403":
description: |
The user must do something in order to use this endpoint. One example
is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
content:
application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

223
data/api/identity/v2_terms.yaml
View file

@ -11,22 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Terms of Service 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
title: Matrix Identity Service Terms of Service API
version: 2.0.0
paths:
"/terms":
/terms:
get:
summary: Gets the terms of service offered by the server.
description: |-
@ -34,81 +24,85 @@ paths:
to filter through the terms to determine which terms need acceptance from the
user. Note that this endpoint does not require authentication.
operationId: getTerms
parameters: []
responses:
200:
description: |-
The terms of service offered by the server.
examples:
application/json: {
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
schema:
type: object
properties:
policies:
"200":
description: The terms of service offered by the server.
content:
application/json:
schema:
type: object
title: Policy Map
description: |-
The policies the server offers. Mapped from arbitrary ID (unused in
this version of the specification) to a Policy Object.
additionalProperties:
type: object
title: Policy Object
description: |-
The policy. Includes a map of language (ISO 639-2) to language-specific
policy information.
properties:
version:
type: string
description: |-
The version for the policy. There are no requirements on what this
might be and could be "alpha", semantically versioned, or arbitrary.
required: ['version']
# TODO: TravisR - Make this render
additionalProperties:
properties:
policies:
type: object
title: Internationalised Policy
title: Policy Map
description: |-
The policy information for the specified language.
properties:
name:
type: string
description: The translated name of the policy.
url:
type: string
description: |-
The URL, which should include the policy ID, version, and language
in it, to be presented to the user as the policy. URLs should have
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the `m.accepted_terms` collection.
required: ['name', 'url']
required: ['policies']
The policies the server offers. Mapped from arbitrary ID (unused in
this version of the specification) to a Policy Object.
additionalProperties:
type: object
title: Policy Object
description: |-
The policy. Includes a map of language (ISO 639-2) to language-specific
policy information.
properties:
version:
type: string
description: |-
The version for the policy. There are no requirements on what this
might be and could be "alpha", semantically versioned, or arbitrary.
required:
- version
# TODO: TravisR - Make this render
additionalProperties:
type: object
title: Internationalised Policy
description: The policy information for the specified language.
properties:
name:
type: string
description: The translated name of the policy.
url:
type: string
description: |-
The URL, which should include the policy ID, version, and language
in it, to be presented to the user as the policy. URLs should have
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the `m.accepted_terms` collection.
required:
- name
- url
required:
- policies
examples:
response:
value: {
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
post:
summary: Indicates acceptance of terms to the server.
description: |-
@ -126,24 +120,43 @@ paths:
operationId: agreeToTerms
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
user_accepts:
type: array
items:
type: string
description: The URLs the user is accepting in this request.
example: "https://example.org/somewhere/terms-2.0-en.html"
required: ['user_accepts']
requestBody:
content:
application/json:
schema:
type: object
properties:
user_accepts:
type: array
items:
type: string
description: The URLs the user is accepting in this request.
example: https://example.org/somewhere/terms-2.0-en.html
required:
- user_accepts
responses:
200:
description: |-
The server has considered the user as having accepted the provided URLs.
examples:
application/json: {}
schema:
type: object
"200":
description: The server has considered the user as having accepted the provided
URLs.
content:
application/json:
schema:
type: object
examples:
response:
value: {}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity/v2
components:
securitySchemes:
$ref: definitions/security.yaml

64
data/api/identity/versions.yaml
View file

@ -11,18 +11,12 @@
# 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'
openapi: 3.1.0
info:
title: "Matrix Identity Service Versions API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
title: Matrix Identity Service Versions API
version: 1.0.0
paths:
"/versions":
/versions:
get:
x-addedInMatrixVersion: "1.1"
summary: Gets the versions of the specification supported by the server.
@ -36,19 +30,39 @@ paths:
All supported versions, including patch versions, are reported by the server.
operationId: getVersions
responses:
200:
"200":
description: The versions supported by the server.
examples:
application/json: {
"versions": ["r0.2.0", "r0.2.1", "v1.1"]
}
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions.
required: ['versions']
content:
application/json:
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions.
required:
- versions
examples:
response:
value: {
"versions": [
"r0.2.0",
"r0.2.1",
"v1.1"
]
}
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8090
basePath:
default: /_matrix/identity