From 9efd021f5e1340966659035e44099264a298397f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 6 May 2016 16:47:49 +0100 Subject: [PATCH] Document the user-interactive api params Document the parameters and responses on /register and /account/password which are invoved in the user-interactive auth --- api/client-server/administrative_contact.yaml | 16 ++++-- api/client-server/definitions/auth_data.yaml | 20 ++++++++ .../definitions/auth_response.yaml | 49 +++++++++++++++++++ api/client-server/registration.yaml | 18 ++++--- 4 files changed, 93 insertions(+), 10 deletions(-) create mode 100644 api/client-server/definitions/auth_data.yaml create mode 100644 api/client-server/definitions/auth_response.yaml diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 50a808c7f..44ac251a1 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -18,6 +18,8 @@ paths: post: summary: Changes a user's password. description: |- + Changes the password for an account on this homeserver. + 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. @@ -30,14 +32,15 @@ paths: name: body schema: type: object - example: |- - { - "new_password": "ihatebananas" - } properties: new_password: type: string description: The new password for the account. + example: "ihatebananas" + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + "$ref": "definitions/auth_data.yaml" required: ["new_password"] responses: 200: @@ -46,6 +49,11 @@ paths: application/json: "{}" schema: type: object + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" 429: description: This request was rate-limited. schema: diff --git a/api/client-server/definitions/auth_data.yaml b/api/client-server/definitions/auth_data.yaml new file mode 100644 index 000000000..d9c93d214 --- /dev/null +++ b/api/client-server/definitions/auth_data.yaml @@ -0,0 +1,20 @@ +title: Authentication Data +description: |- + Used by clients to submit authentication information to the interactive-authentication API +type: object +properties: + type: + description: The login type that the client is attempting to complete. + type: string + session: + description: The value of the session key given by the homeserver. + type: string +additionalProperties: + description: Keys dependent on the login type + type: object +required: + - type +example: + type: "example.type.foo" + session: "xxxxx" + example_credential: "verypoorsharedsecret" diff --git a/api/client-server/definitions/auth_response.yaml b/api/client-server/definitions/auth_response.yaml new file mode 100644 index 000000000..3fd800ea9 --- /dev/null +++ b/api/client-server/definitions/auth_response.yaml @@ -0,0 +1,49 @@ +title: Authentication response +description: |- + Used by servers to indicate that additional authentication information is required, +type: object +properties: + flows: + description: A list of the login flows supported by the server for this API. + title: Flow information + type: array + items: + type: object + properties: + stages: + description: |- + The login type of each of the stages required to complete this + authentication flow + type: array + items: + type: string + example: "example.type.foo" + required: + - stages + params: + type: object + description: |- + Contains any information that the client will need to know in order to + use a given type of authentication. For each login type presented, + that type may be present as a key in this dictionary. For example, the + public part of an OAuth client ID could be given here. + additionalProperties: + type: object + example: + "example.type.baz": { "example_key": "foobar" } + session: + type: string + description: |- + This is a session identifier that the client must pass back to the home + server, if one is provided, in subsequent attempts to authenticate in the + same API call. + example: "xxxxxxyz" + completed: + type: array + description: |- + A list of the stages the client has completed successfully + items: + type: string + example: "example.type.foo" +required: + - flows diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 3818fc348..03a3cdfbd 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -39,26 +39,27 @@ paths: name: body schema: type: object - example: |- - { - "username": "cheeky_monkey", - "password": "ilovebananas", - "bind_email": false - } properties: + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + "$ref": "definitions/auth_data.yaml" bind_email: type: boolean description: |- If true, the server binds the email used for authentication to the Matrix ID with the ID Server. + example: false username: type: string description: |- The local part of the desired Matrix ID. If omitted, the homeserver MUST generate a Matrix ID local part. + example: cheeky_monkey password: type: string description: The desired password for the account. + example: ilovebananas required: ["password"] responses: 200: @@ -118,6 +119,11 @@ paths: "errcode": "M_USER_IN_USE", "error": "Desired user ID is already taken." } + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" 429: description: This request was rate-limited. schema: