mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-24 09:58:38 +01:00
Merge pull request #109 from matrix-org/registration-swagger
Swaggerify /register endpoint
This commit is contained in:
Kegsay
commit
c032eafd4e
101
api/client-server/v2_alpha/registration.yaml
Normal file
101
api/client-server/v2_alpha/registration.yaml
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server v2 Registration API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/api/v2_alpha
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
paths:
|
||||
"/register":
|
||||
post:
|
||||
summary: Register for an account on this homeserver.
|
||||
description: |-
|
||||
Register for an account on this homeserver.
|
||||
parameters:
|
||||
- in: body
|
||||
name: body
|
||||
schema:
|
||||
type: object
|
||||
example: |-
|
||||
{
|
||||
"username": "cheeky_monkey",
|
||||
"password": "ilovebananas",
|
||||
"bind_email": false
|
||||
}
|
||||
properties:
|
||||
bind_email:
|
||||
type: boolean
|
||||
description: |-
|
||||
If true, the server binds the email used for authentication to
|
||||
the Matrix ID with the ID Server.
|
||||
username:
|
||||
type: string
|
||||
description: |-
|
||||
The local part of the desired Matrix ID. If omitted,
|
||||
the homeserver MUST generate a Matrix ID local part.
|
||||
password:
|
||||
type: string
|
||||
description: The desired password for the account.
|
||||
required: ["password"]
|
||||
responses:
|
||||
200:
|
||||
description: The account has been registered.
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"user_id": "@cheeky_monkey:matrix.org",
|
||||
"access_token": "abc123",
|
||||
"home_server": "matrix.org",
|
||||
"refresh_token": "def456"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
description: The fully-qualified Matrix ID that has been registered.
|
||||
access_token:
|
||||
type: string
|
||||
description: |-
|
||||
An access token for the account.
|
||||
This access token can then be used to authorize other requests.
|
||||
The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
|
||||
There is no specific error message to indicate that a request has failed because
|
||||
an access token has expired; instead, if a client has reason to believe its
|
||||
access token is valid, and it receives an auth error, they should attempt to
|
||||
refresh for a new token on failure, and retry the request with the new token.
|
||||
refresh_token:
|
||||
type: string
|
||||
# TODO: Work out how to linkify /tokenrefresh
|
||||
description: |-
|
||||
(optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
|
||||
home_server:
|
||||
type: string
|
||||
description: The hostname of the Home Server on which the account has been registered.
|
||||
400:
|
||||
description: |-
|
||||
Part of the request was invalid. This may include one of the following error codes:
|
||||
|
||||
* ``M_USER_IN_USE`` : The desired user ID is already taken.
|
||||
* ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
|
||||
claimed by an application service.
|
||||
|
||||
These errors may be returned at any stage of the registration process,
|
||||
including after authentication if the requested user ID was registered
|
||||
whilst the client was performing authentication.
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"errcode": "M_USER_IN_USE",
|
||||
"error": "Desired user ID is already taken."
|
||||
}
|
||||
429:
|
||||
description: This request was rate-limited.
|
||||
schema:
|
||||
"$ref": "definitions/error.yaml"
|
||||
|
|
@ -974,6 +974,107 @@ member's state, by making a request to
|
|||
"membership": "ban"
|
||||
}
|
||||
|
||||
Account operations
|
||||
------------------
|
||||
|
||||
Registration
|
||||
~~~~~~~~~~~~
|
||||
This API endpoint uses the `User-Interactive Authentication API`_.
|
||||
|
||||
{{v2_registration_http_api}}
|
||||
|
||||
Login
|
||||
~~~~~
|
||||
|
||||
{{login_http_api}}
|
||||
|
||||
Changing Password
|
||||
~~~~~~~~~~~~~~~~~
|
||||
This section refers to API Version 2. These API calls currently use the prefix
|
||||
``/_matrix/client/v2_alpha``.
|
||||
|
||||
Request::
|
||||
|
||||
POST $V2PREFIX/account/password
|
||||
|
||||
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.
|
||||
|
||||
The body of the POST request is a JSON object containing:
|
||||
|
||||
new_password
|
||||
The new password for the account.
|
||||
|
||||
On success, an empty JSON object is returned.
|
||||
|
||||
The error code M_NOT_FOUND is returned if the user authenticated with a third
|
||||
party identifier but the Home Server could not find a matching account in its
|
||||
database.
|
||||
|
||||
Adding a Third Party Identifier
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
This section refers to API Version 2. These API calls currently use the prefix
|
||||
``/_matrix/client/v2_alpha``.
|
||||
|
||||
Request::
|
||||
|
||||
POST $V2PREFIX/account/3pid
|
||||
|
||||
Used to add a third party identifier to the user's account.
|
||||
|
||||
The body of the POST request is a JSON object containing:
|
||||
|
||||
threePidCreds
|
||||
An object containing third party identifier credentials.
|
||||
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 third party identifier credentials 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 Third Party Identifiers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
This section refers to API Version 2. These API calls currently use the prefix
|
||||
``/_matrix/client/v2_alpha``.
|
||||
|
||||
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
|
||||
|
||||
|
||||
Profiles
|
||||
--------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue