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

Swaggerify /account

Browse source
This commit is contained in:
Daniel Wagner-Hall 2015-12-01 13:53:03 +00:00
parent 79244e8065
commit c6e0322a9e
2 changed files with 160 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

157
api/client-server/administrative_contact.yaml Normal file
View file

@ -0,0 +1,157 @@
swagger: '2.0'
info:
title: "Matrix Client-Server v1 Account Administrative Contact API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v2_alpha
consumes:
- application/json
produces:
- application/json
securityDefinitions:
accessToken:
type: apiKey
description: The user_id or application service access_token
name: access_token
in: query
paths:
"/account/password":
post:
summary: Changes a user's password.
description: |-
This API endpoint uses the User-Interactive Authentication API.
An access token should be submitted to this endpoint if the client has
an active session.
The Home Server may change the flows available depending on whether a
valid access token is provided.
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: |-
{
"new_password": "ihatebananas"
}
properties:
new_password:
type: string
description: The new password for the account.
required: ["new_password"]
responses:
200:
description: The password has been changed.
examples:
application/json: "{}"
schema:
type: object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"/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 Home Server 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.
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:
threePidCreds:
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 home server should also bind this third party
identifier to the account's Matrix ID with the passed identity
server. Default: ``false``.
x-example: true
required: ["threePidCreds"]
example: |-
{
"threePidCreds": {
"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."
}

53
specification/client_server_api.rst
View file

@ -510,58 +510,11 @@ database.
Adding Account Administrative Contact Information
+++++++++++++++++++++++++++++++++++++++++++++++++
Request::
POST $V2PREFIX/account/3pid
A homeserver may keep some contact information for administrative use.
This is independent of any information kept by any Identity Servers.
Used to add contact information to the user's account.
The body of the POST request is a JSON object containing:
threePidCreds
An object containing contact information.
bind
Optional. A boolean indicating whether the Home Server should also bind this
third party identifier to the account's matrix ID with the Identity Server. If
supplied and true, the Home Server must bind the 3pid accordingly.
The contact information object comprises:
id_server
The colon-separated hostname and port of the Identity Server used to
authenticate the third party identifier. If the port is the default, it and the
colon should be omitted.
sid
The session ID given by the Identity Server
client_secret
The client secret used in the session with the Identity Server.
On success, the empty JSON object is returned.
May also return error codes:
M_THREEPID_AUTH_FAILED
If the credentials provided could not be verified with the ID Server.
Fetching Currently Associated Contact Information
+++++++++++++++++++++++++++++++++++++++++++++++++
Request::
GET $V2PREFIX/account/3pid
This returns a list of third party identifiers that the Home Server 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 Home Server as, for example, identifiers that it
will accept to reset the user's account password.
Returns a JSON object with the key ``threepids`` whose contents is an array of
objects with the following keys:
medium
The medium of the 3pid (eg, ``email``)
address
The textual address of the 3pid, eg. the email address
{{administrative_contact_http_api}}
Pagination
----------