openapi: 3.0.1 info: title: Identity API description: | The purpose of an identity server is to validate, store, and answer questions about the identities of users. In particular, it stores associations of the form "identifier X represents the same user as identifier Y", where identities may exist on different systems (such as email addresses, phone numbers, Matrix user IDs, etc). The identity server has some private-public keypairs. When asked about an association, it will sign details of the association with its private key. Clients may validate the assertions about associations by verifying the signature with the public key of the identity server.In general, identity servers are treated as reliable oracles. They do not necessarily provide evidence that they have validated associations, but claim to have done so. Establishing the trustworthiness of an individual identity server is left as an exercise for the client. contact: name: Anatoly Sablin email: tolya@sablin.xyz license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 0.2.1 paths: /_matrix/identity/v2/account: get: summary: Gets information about what user owns the access token used in the request. operationId: getInfo responses: 200: description: The token holder's information. content: application/json: schema: $ref: '#/components/schemas/OpenIdInfo' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Logs out the access token, preventing it from being used to authenticate future requests to the server. operationId: logout responses: 200: description: The token was successfully logged out. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 401: description: The token is not registered or is otherwise unknown to the server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2/account/register: post: summary: Exchanges an OpenID token from the homeserver for an access token to access the identity server. description: The request body is the same as the values returned by /openid/request_token in the Client-Server API. operationId: register requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/OpenIdRequest' responses: 200: description: A token which can be used to authenticate future requests to the identity server. content: application/json: schema: $ref: '#/components/schemas/Token' /_matrix/identity/v2/store-invite: post: summary: Store pending invitations to a user's 3pid. description: In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in the invite message generation described below. The service will generate a random token and an ephemeral key used for accepting the invite. The service also generates a display_name for the inviter, which is a redacted version of address which does not leak the full contents of the address. The service records persistently all of the above information. It also generates an email containing all of this data, sent to the address parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on requests to /_matrix/identity/api/v1/pubkey/ephemeral/isvalid. Currently, invites may only be issued for 3pids of the email medium. operationId: invite requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/InvitationRequest' responses: 200: description: The invitation was stored. content: application/json: schema: $ref: '#/components/schemas/InvitationResponse' 400: description: An error has occured. 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. content: application/json: schema: $ref: '#/components/schemas/MxidErrorResponse' /_matrix/identity/v2/pubkey/{keyId}: get: summary: Get the public key for the passed key ID. operationId: get parameters: - name: keyId in: path 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. required: true schema: type: string responses: 200: description: The public key exists. content: application/json: schema: $ref: '#/components/schemas/PublicKeyResponse' 404: description: The public key was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2/pubkey/isvalid: get: summary: Check whether a long-term public key is valid. description: The response should always be the same, provided the key exists. operationId: valid parameters: - name: public_key in: query description: The unpadded base64-encoded public key to check. required: true schema: type: string responses: 200: description: The validity of the public key. content: application/json: schema: $ref: '#/components/schemas/KeyValidationResponse' /_matrix/identity/v2/pubkey/ephemeral/isvalid: get: summary: Check whether a short-term public key is valid. operationId: ephemeralValid parameters: - name: public_key in: query description: The unpadded base64-encoded public key to check. required: true schema: type: string responses: 200: description: The validity of the public key. content: application/json: schema: $ref: '#/components/schemas/KeyValidationResponse' /_matrix/identity/v2/lookup: post: summary: Look up the Matrix user ID for a 3pid. operationId: lookup requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/LookupRequest' responses: 200: description: The association for that 3pid, or an empty object if no association is known. content: application/json: schema: $ref: '#/components/schemas/SingleLookupResponse' /_matrix/identity/v2/hash_details: get: summary: Gets parameters for hashing identifiers from the server. description: This can include any of the algorithms defined in this specification. operationId: hashDetails responses: 200: description: The hash function information. content: application/json: schema: $ref: '#/components/schemas/HashDetails' /_matrix/identity/v2/validate/msisdn/requestToken: post: summary: Create a session for validating a phone number. description: |- The identity server will send an SMS message containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number. Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/msisdn/requestToken is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server. operationId: createPhoneSession requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/PhoneRequestToken' required: true responses: 200: description: Session created. content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 400: description: An error occured. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2/validate/msisdn/submitToken: get: summary: Validate ownership of an email address. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specifiedas application/x-form-www-urlencoded data. However, this usage is deprecated. operationId: getValidatePhone parameters: - name: sid in: query description: The session ID, generated by the requestToken call. required: true schema: type: string - name: client_secret in: query description: The client secret that was supplied to the requestToken call. required: true schema: type: string - name: token in: query description: The token generated by the requestToken call and sent to the user. required: true schema: type: string responses: 200: description: Phone number is validated. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 302: 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 400: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Validate ownership of a phone number. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. operationId: postValidatePhone requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/SubmitToken' required: true responses: 200: description: The success of the validation. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' /_matrix/identity/v2/validate/email/submitToken: get: summary: Validate ownership of an email address. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. operationId: getValidateEmail parameters: - name: sid in: query description: The session ID, generated by the requestToken call. required: true schema: type: string - name: client_secret in: query description: The client secret that was supplied to the requestToken call. required: true schema: type: string - name: token in: query description: The token generated by the requestToken call and emailed to the user. required: true schema: type: string responses: 200: description: Email address is validated. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 302: 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 400: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Validate ownership of an email address. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. operationId: postValidateEmail requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/SubmitToken' required: true responses: 200: description: The success of the validation. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' /_matrix/identity/v2/validate/email/requestToken: post: summary: Create a session for validating an email address. description: |- The identity server will send an email containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the email for that email address, and so we validate ownership of the email address. Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example,/register/email/requestToken is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server. operationId: createEmailSession requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/EmailRequestToken' responses: default: content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 200: description: Session created. content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 400: description: An error ocurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2/sign-ed25519: post: summary: Sign invitation details. description: The identity server will look up token which was stored in a call to store-invite, and fetch the sender of the invite. operationId: sign requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/SigningRequest' required: true responses: 200: description: The signed JSON of the mxid, sender, and token. content: application/json: schema: $ref: '#/components/schemas/SigningResponse' 404: description: The token was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2: get: summary: To discover that an Identity server is available at a specific URL, this endpoint can be queried and will return an empty object. description: This is primarly used for auto-discovery and health check purposes by entities acting as a client for the Identity server. operationId: v1Status responses: 200: description: An identity server is ready to serve requests. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' /_matrix/identity/v2/terms: get: summary: Gets all the terms of service offered by the server. description: The client is expected to filter through the terms to determine which terms need acceptance from the user. Note that this endpoint does not require authentication. operationId: get_1 responses: 200: description: The terms of service offered by the server. content: application/json: schema: $ref: '#/components/schemas/TermsResponse' post: summary: Called by a client to indicate that the user has accepted/agreed to the included set of URLs. description: Servers MUST NOT assume that the client will be sending all previously accepted URLs and should therefore append the provided URLs to what the server already knows has been accepted. operationId: accepts requestBody: content: application/json: schema: $ref: '#/components/schemas/UserAccepts' responses: 200: description: The server has considered the user as having accepted the provided URLs. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' /_matrix/identity/v2/3pid/getValidated3pid: get: summary: Determines if a given 3pid has been validated by a user. operationId: validate parameters: - name: sid in: query description: The Session ID generated by the requestToken call. required: true schema: type: string - name: client_secret in: query description: The client secret passed to the requestToken call. required: true schema: type: string responses: 200: description: Validation information for the session. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' 400: description: he 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The Session ID or client secret were not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2/bind: post: summary: Publish an association between a session and a Matrix user ID. description: Future calls to /lookup for any of the session's 3pids will return this association. operationId: bind requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/PublishRequest' required: true responses: 200: description: The association was published. content: application/json: schema: $ref: '#/components/schemas/PublishResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: he Session ID or client secret were not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/v2/unbind: post: summary: Remove an association between a session and a Matrix user ID. description: Future calls to /lookup for any of the session's 3pids will not return the removed association. operationId: unbind requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/UnbindRequest' required: true responses: 200: description: The association was successfully removed. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: The credentials supplied to authenticate the request were invalid. This may also be returned if the identity server does not support the chosen authentication method(such as blocking homeservers from unbinding identifiers). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1/validate/email/requestToken: post: summary: Create a session for validating an email address. description: |- The identity server will send an email containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the email for that email address, and so we validate ownership of the email address. Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example,/register/email/requestToken is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server. operationId: createEmailSession_1 requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/EmailRequestToken' responses: default: content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 200: description: Session created. content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 400: description: An error ocurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1/validate/email/submitToken: get: summary: Validate ownership of an email address. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. operationId: getValidateEmail_1 parameters: - name: sid in: query description: The session ID, generated by the requestToken call. required: true schema: type: string - name: client_secret in: query description: The client secret that was supplied to the requestToken call. required: true schema: type: string - name: token in: query description: The token generated by the requestToken call and emailed to the user. required: true schema: type: string responses: 200: description: Email address is validated. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 302: 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 400: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Validate ownership of an email address. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. operationId: postValidateEmail_1 requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/SubmitToken' required: true responses: 200: description: The success of the validation. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' /_matrix/identity/api/v1/validate/msisdn/requestToken: post: summary: Create a session for validating a phone number. description: |- The identity server will send an SMS message containing a token. If that token is presented to the identity server in the future, it indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number. Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, /register/msisdn/requestToken is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server. operationId: createPhoneSession_1 requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/PhoneRequestToken' required: true responses: 200: description: Session created. content: application/json: schema: $ref: '#/components/schemas/SessionResponse' 400: description: An error occured. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1/validate/msisdn/submitToken: get: summary: Validate ownership of an email address. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specifiedas application/x-form-www-urlencoded data. However, this usage is deprecated. operationId: getValidatePhone_1 parameters: - name: sid in: query description: The session ID, generated by the requestToken call. required: true schema: type: string - name: client_secret in: query description: The client secret that was supplied to the requestToken call. required: true schema: type: string - name: token in: query description: The token generated by the requestToken call and sent to the user. required: true schema: type: string responses: 200: description: Phone number is validated. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 302: 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 400: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Validate ownership of a phone number. description: |- If the three parameters are consistent with a set generated by a requestToken call, ownership of the email address is considered to have been validated. This does not publish any information publicly, or associate the email address with any Matrix user ID. Specifically, calls to /lookup will not show a binding. The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the identity server. Clients must always pass on the token without modification. operationId: postValidatePhone_1 requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/SubmitToken' required: true responses: 200: description: The success of the validation. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' /_matrix/identity/api/v1/bind: post: summary: Publish an association between a session and a Matrix user ID. description: Future calls to /lookup for any of the session's 3pids will return this association. operationId: bind_1 requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/PublishRequest' required: true responses: 200: description: The association was published. content: application/json: schema: $ref: '#/components/schemas/PublishResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: he Session ID or client secret were not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1/store-invite: post: summary: Store pending invitations to a user's 3pid. description: In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in the invite message generation described below. The service will generate a random token and an ephemeral key used for accepting the invite. The service also generates a display_name for the inviter, which is a redacted version of address which does not leak the full contents of the address. The service records persistently all of the above information. It also generates an email containing all of this data, sent to the address parameter, notifying them of the invitation. Also, the generated ephemeral public key will be listed as valid on requests to /_matrix/identity/api/v1/pubkey/ephemeral/isvalid. Currently, invites may only be issued for 3pids of the email medium. operationId: invite_1 requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/InvitationRequest' responses: 200: description: The invitation was stored. content: application/json: schema: $ref: '#/components/schemas/InvitationResponse' 400: description: An error has occured. 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. content: application/json: schema: $ref: '#/components/schemas/MxidErrorResponse' /_matrix/identity/api/v1/pubkey/{keyId}: get: summary: Get the public key for the passed key ID. operationId: get_2 parameters: - name: keyId in: path 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. required: true schema: type: string responses: 200: description: The public key exists. content: application/json: schema: $ref: '#/components/schemas/PublicKeyResponse' 404: description: The public key was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1/pubkey/isvalid: get: summary: Check whether a long-term public key is valid. description: The response should always be the same, provided the key exists. operationId: valid_1 parameters: - name: public_key in: query description: The unpadded base64-encoded public key to check. required: true schema: type: string responses: 200: description: The validity of the public key. content: application/json: schema: $ref: '#/components/schemas/KeyValidationResponse' /_matrix/identity/api/v1/pubkey/ephemeral/isvalid: get: summary: Check whether a short-term public key is valid. operationId: ephemeralValid_1 parameters: - name: public_key in: query description: The unpadded base64-encoded public key to check. required: true schema: type: string responses: 200: description: The validity of the public key. content: application/json: schema: $ref: '#/components/schemas/KeyValidationResponse' /_matrix/identity/api/v1/lookup: get: summary: Look up the Matrix user ID for a 3pid. operationId: lookup_1 parameters: - name: medium in: query description: The medium type of the 3pid. See the 3PID Types Appendix. required: true schema: type: string - name: address in: query description: The address of the 3pid being looked up. See the 3PID Types Appendix. required: true schema: type: string responses: 200: description: The association for that 3pid, or an empty object if no association is known. content: application/json: schema: $ref: '#/components/schemas/SingleLookupResponse' /_matrix/identity/api/v1/bulk_lookup: post: summary: Lookup Matrix user IDs for a list of 3pids. operationId: bulkLookup requestBody: description: An array of arrays containing the 3PID Types with the medium in first position and the address in second position. content: application/json: schema: $ref: '#/components/schemas/BulkLookupRequest' required: true responses: 200: description: A list of known 3PID mappings for the supplied 3PIDs. content: application/json: schema: $ref: '#/components/schemas/BulkLookupResponse' /_matrix/identity/api/v1/sign-ed25519: post: summary: Sign invitation details. description: The identity server will look up token which was stored in a call to store-invite, and fetch the sender of the invite. operationId: sign_1 requestBody: description: JSON body request. content: application/json: schema: $ref: '#/components/schemas/SigningRequest' required: true responses: 200: description: The signed JSON of the mxid, sender, and token. content: application/json: schema: $ref: '#/components/schemas/SigningResponse' 404: description: The token was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1: get: summary: To discover that an Identity server is available at a specific URL, this endpoint can be queried and will return an empty object. description: This is primarly used for auto-discovery and health check purposes by entities acting as a client for the Identity server. operationId: v1Status_1 responses: 200: description: An identity server is ready to serve requests. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' /_matrix/identity/api/v1/3pid/getValidated3pid: get: summary: Determines if a given 3pid has been validated by a user. operationId: validate_1 parameters: - name: sid in: query description: The Session ID generated by the requestToken call. required: true schema: type: string - name: client_secret in: query description: The client secret passed to the requestToken call. required: true schema: type: string responses: 200: description: Validation information for the session. content: application/json: schema: $ref: '#/components/schemas/ValidationResponse' 400: description: he 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 404: description: The Session ID or client secret were not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /_matrix/identity/api/v1/unbind: post: summary: Remove an association between a session and a Matrix user ID. description: Future calls to /lookup for any of the session's 3pids will not return the removed association. operationId: unbind_1 requestBody: description: JSON body request content: application/json: schema: $ref: '#/components/schemas/UnbindRequest' required: true responses: 200: description: The association was successfully removed. content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 403: description: The credentials supplied to authenticate the request were invalid. This may also be returned if the identity server does not support the chosen authentication method(such as blocking homeservers from unbinding identifiers). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: OpenIdInfo: required: - user_id type: object properties: user_id: type: string description: The user ID which registered the token. description: OpenID info ErrorResponse: type: object properties: errcode: type: string error: type: string Token: required: - token type: object properties: token: type: string description: An opaque string representing the token to authenticate future requests to the identity server with. description: Token. OpenIdRequest: type: object properties: access_token: type: string description: An access token the consumer may use to verify the identity of the person who generated the token. This is given to the federation API GET /openid/userinfo. token_type: type: string description: The string Bearer. matrix_server_name: type: string description: The homeserver domain the consumer should use when attempting to verify the user's identity. expires_in: type: integer description: The number of seconds before this token expires and a new one must be generated. format: int64 description: JSON body request of the OpenID API. EmptyResponse: type: object description: Empty response InvitationResponse: required: - display_name - public_keys - token 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: string description: A list of [server's long-term public key, generated ephemeral public key]. display_name: type: string description: The generated (redacted) display_name. description: Result of the pending invitation. MxidErrorResponse: type: object properties: errcode: type: string error: type: string mxid: type: string description: The MXID. description: The Matrix error response with the MXID. InvitationRequest: required: - address - medium - room_id - sender type: object properties: medium: type: string description: The literal string email address: type: string description: The email address of the invited user. sender: type: string description: The Matrix user ID of the inviting user. room_id: type: string description: The Matrix room ID to which the user is invited. description: JSON boy request of the invitation api. PublicKeyResponse: required: - public_key type: object properties: public_key: type: string description: Unpadded Base64 encoded public key. description: The public key exists. KeyValidationResponse: required: - valid type: object properties: valid: type: boolean description: Whether the public key is recognised and is currently valid. description: The validity of the public key. SingleLookupResponse: required: - address - medium - mxid - not_after - not_before - signatures - ts type: object properties: address: type: string description: The 3pid address of the user being looked up, matching the address requested. medium: type: string description: A medium from the 3PID Types Appendix, matching the medium requested. mxid: type: string description: The Matrix user ID associated with the 3pid. ts: type: integer description: The unix timestamp at which the association was verified. format: int64 signatures: type: object additionalProperties: type: object additionalProperties: type: string 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. description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. not_before: type: integer description: A unix timestamp before which the association is not known to be valid. format: int64 not_after: type: integer description: A unix timestamp after which the association is not known to be valid. format: int64 description: Look up response the Matrix user ID for a 3pid. LookupRequest: required: - addresses - algorithm - pepper 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. pepper: type: string description: The pepper from /hash_details. This is required even when the algorithm does not make use of it. addresses: type: array 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. 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. description: JSON body request. HashDetails: required: - algorithms - lookup_pepper type: object properties: algorithms: type: array description: The algorithms the server supports. Must contain at least sha256. items: type: string description: The algorithms the server supports. Must contain at least sha256. 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. description: Hash details. SessionResponse: required: - sid type: object properties: sid: type: string description: The session ID. Session IDs are opaque strings generated by the identity server. They must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty. submit_url: type: string description: An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API's POST /validate/email/submitToken endpoint. The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client. description: The sid generated for this session to the caller, in a JSON object containing the sid key. PhoneRequestToken: required: - client_secret - country - phone_number - send_attempt type: object properties: country: type: string description: The two-letter uppercase ISO country code that the number in phone_number should be parsed as if it were dialled from. client_secret: type: string description: A unique string generated by the client, and used to identify the validation attempt. It 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. phone_number: type: string description: The phone number to validate. send_attempt: type: integer description: The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server.The client should increment this value if they desire a new email(e.g.a reminder) to be sent. format: int64 next_link: type: string description: When the validation is completed, the identity server will redirect the user to this URL. description: JSON body request of the creating an phone association. ValidationResponse: required: - address - medium - validated_at 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 description: Timestamp, in milliseconds, indicating the time that the 3pid was validated. format: int64 description: Validation result. SubmitToken: required: - client_secret - sid - token type: object properties: sid: type: string description: The session ID, generated by the requestToken call. token: type: string description: The token generated by the requestToken call and sent to the user. client_secret: type: string description: The client secret that was supplied to the requestToken call. description: JSON body request of the validation. EmailRequestToken: required: - client_secret - email - send_attempt type: object properties: email: type: string description: The email address to validate. client_secret: type: string description: A unique string generated by the client, and used to identify the validation attempt. It 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. send_attempt: type: integer description: The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server.The client should increment this value if they desire a new email(e.g.a reminder) to be sent. format: int64 next_link: type: string description: When the validation is completed, the identity server will redirect the user to this URL. description: JSON body request of the creating an email association. SigningResponse: required: - mxid - sender - signatures - token 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: type: object additionalProperties: type: object additionalProperties: type: string description: The signature of the mxid, sender, and token. description: The signature of the mxid, sender, and token. description: The signature of the mxid, sender, and token. token: type: string description: The token for the invitation. description: JSON body response of the signing api. SigningRequest: required: - mxid - private_key - token type: object 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. description: JSON body request of the signing api. TermsResponse: type: object properties: policies: type: object additionalProperties: type: object additionalProperties: type: object description: Policies. description: Policies. description: Policies. description: All the terms of service offer by the server UserAccepts: required: - accepts type: object properties: accepts: type: array description: The URLs the user is accepting in this request. items: type: string description: The URLs the user is accepting in this request. description: User accepts. PublishResponse: required: - address - medium - mxid - not_after - not_before - signatures - ts 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. ts: type: integer description: The unix timestamp at which the association was verified. format: int64 signatures: type: object additionalProperties: type: object additionalProperties: type: string description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services. description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services. description: The signatures of the verifying identity servers which show that the association should be trusted, if you trust the verifying identity services. not_before: type: integer description: A unix timestamp before which the association is not known to be valid. format: int64 not_after: type: integer description: A unix timestamp after which the association is not known to be valid. format: int64 description: Result of the publishing association. PublishRequest: required: - client_secret - mxid - sid type: object properties: sid: type: string description: The Session ID generated by the requestToken call. mxid: type: string description: The Matrix user ID to associate with the 3pids. client_secret: type: string description: The client secret passed to the requestToken call. description: JSON body request of the bind api. ThreePid: required: - address - medium type: object properties: medium: type: string description: A medium from the 3PID Types Appendix, matching the medium of the identifier to unbind. address: type: string description: The 3PID address to remove. description: 3PID. UnbindRequest: required: - mxid type: object properties: sid: type: string description: The Session ID generated by the requestToken call. mxid: type: string description: The Matrix user ID to remove from the 3pids. threepid: $ref: '#/components/schemas/ThreePid' client_secret: type: string description: The client secret passed to the requestToken call. description: Unbind request. BulkLookupResponse: required: - threepids type: object properties: threepids: type: array description: An array of array containing the 3PID Types with the medium in first position, the address in second position and Matrix user ID in third position. items: type: array description: An array of array containing the 3PID Types with the medium in first position, the address in second position and Matrix user ID in third position. items: type: string description: An array of array containing the 3PID Types with the medium in first position, the address in second position and Matrix user ID in third position. description: Response of the lookup Matrix user IDs for a list of 3pids. BulkLookupRequest: required: - threepids type: object properties: threepids: type: array description: An array of arrays containing the 3PID Types with the medium in first position and the address in second position. items: type: array description: An array of arrays containing the 3PID Types with the medium in first position and the address in second position. items: type: string description: An array of arrays containing the 3PID Types with the medium in first position and the address in second position. description: Request of the lookup Matrix user IDs for a list of 3pids.