mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-20 16:38:37 +01:00
3bce28a15c
* Use the terminology 'login type' everywhere instead of mixing up 'stage type' and 'login type' * Don't have a separate 'APIs using the User-Interactive Authentication mechanism' section, because (a) it doesn't make much sense to organise the APIs this way, and (b) it was a set of lies anyway. * Move '/account/password' definition into registration.yaml so that register and password can share a section in the spec; remove duplicate doc for /password. * Write some words on using 3pids for /login
122 lines
3.9 KiB
YAML
122 lines
3.9 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server Account Administrative Contact API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/account/3pid":
|
|
get:
|
|
summary: Gets a list of a user's third party identifiers.
|
|
description: |-
|
|
Gets a list of the third party identifiers that the homeserver has
|
|
associated with the user's account.
|
|
|
|
This is *not* the same as the list of third party identifiers bound to
|
|
the user's Matrix ID in Identity Servers.
|
|
|
|
Identifiers in this list may be used by the homeserver as, for example,
|
|
identifiers that it will accept to reset the user's account password.
|
|
security:
|
|
- accessToken: []
|
|
responses:
|
|
200:
|
|
description: The lookup was successful.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"threepids": [
|
|
{
|
|
"medium": "email",
|
|
"address": "monkey@banana.island"
|
|
}
|
|
]
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
threepids:
|
|
type: array
|
|
items:
|
|
type: object
|
|
title: Third party identifier
|
|
properties:
|
|
medium:
|
|
type: string
|
|
description: The medium of the third party identifier.
|
|
enum: ["email"]
|
|
address:
|
|
type: string
|
|
description: The third party identifier address.
|
|
tags:
|
|
- User data
|
|
post:
|
|
summary: Adds contact information to the user's account.
|
|
description: Adds contact information to the user's account.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
type: object
|
|
properties:
|
|
three_pid_creds:
|
|
title: "ThreePidCredentials"
|
|
type: object
|
|
description: The third party credentials to associate with the account.
|
|
properties:
|
|
client_secret:
|
|
type: string
|
|
description: The client secret used in the session with the Identity Server.
|
|
id_server:
|
|
type: string
|
|
description: The Identity Server to use.
|
|
sid:
|
|
type: string
|
|
description: The session identifier given by the Identity Server.
|
|
required: ["client_secret", "id_server", "sid"]
|
|
bind:
|
|
type: boolean
|
|
description: |-
|
|
Whether the homeserver should also bind this third party
|
|
identifier to the account's Matrix ID with the passed identity
|
|
server. Default: ``false``.
|
|
x-example: true
|
|
required: ["three_pid_creds"]
|
|
example: |-
|
|
{
|
|
"three_pid_creds": {
|
|
"id_server": "matrix.org",
|
|
"sid": "abc123987",
|
|
"client_secret": "d0n'tT3ll"
|
|
},
|
|
"bind": false
|
|
}
|
|
responses:
|
|
200:
|
|
description: The addition was successful.
|
|
examples:
|
|
application/json: "{}"
|
|
schema:
|
|
type: object
|
|
403:
|
|
description: The credentials could not be verified with the identity server.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"errcode": "M_THREEPID_AUTH_FAILED",
|
|
"error": "The third party credentials could not be verified by the identity server."
|
|
}
|
|
tags:
|
|
- User data
|