Swaggerify /register endpoint

Need to move registration/login/auth sections around once #94 lands.
pull/977/head
Kegan Dougal 9 years ago
parent 3146b52f83
commit eca98af896

@ -0,0 +1,95 @@
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. For example, this user ID may be taken. This 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"

@ -1001,52 +1001,17 @@ member's state, by making a request to
} }
Registration Account operations
------------ ------------------
This section refers to API Version 2. These API calls currently use the prefix
``/_matrix/client/v2_alpha``.
Registering for a user account is done using the request::
POST $V2PREFIX/register
Registration
~~~~~~~~~~~~
This API endpoint uses the User-Interactive Authentication API. This API endpoint uses the User-Interactive Authentication API.
This API endpoint does not require an access token.
The body of the POST request is a JSON object containing: {{v2_registration_http_api}}
username Login
Optional. This is the local part of the desired Matrix ID. If omitted, the ~~~~~
Home Server must generate a Matrix ID local part.
password
Required. The desired password for the account.
bind_email
Optional. If ``true``, the server binds the email used for authentication to
the Matrix ID with the ID Server.
On success, this returns a JSON object with keys:
user_id
The fully-qualified Matrix ID that has been registered.
access_token
An access token for the new account.
home_server
The hostname of the Home Server on which the account has been registered.
This endpoint may also return the following error codes:
M_USER_IN_USE
If the Matrix ID is already in use
M_EXCLUSIVE
If the requested Matrix ID is in the exclusive namespace of an application
service.
Home Servers MUST perform the relevant checks and return these codes before
performing User-Interactive Authentication, although they may also return
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
Old V1 API docs: |register|_
{{login_http_api}} {{login_http_api}}

Loading…
Cancel
Save