afd5018494
Part of MSC2140 Convert status codes to strings if there is a string status code. Fixes a build error when we mix 4xx and 403 in the same definition. We also have to correct stringified numbers to pass the build.
131 lines
4.5 KiB
YAML
131 lines
4.5 KiB
YAML
# Copyright 2019 The Matrix.org Foundation C.I.C.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Identity Service Authentication API"
|
|
version: "2.0.0"
|
|
host: localhost:8090
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/identity/v2
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/account/register":
|
|
post:
|
|
summary: Exchanges an OpenID token for an access token.
|
|
description: |-
|
|
Exchanges an OpenID token from the homeserver for an access token to
|
|
access the identity server. The request body is the same as the values
|
|
returned by ``/openid/request_token`` in the Client-Server API.
|
|
operationId: registerAccount
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
schema:
|
|
$ref: "../client-server/definitions/openid_token.yaml"
|
|
responses:
|
|
200:
|
|
description: |-
|
|
A token which can be used to authenticate future requests to the
|
|
identity server.
|
|
examples:
|
|
application/json: {
|
|
"token": "abc123_OpaqueString"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: |-
|
|
An opaque string representing the token to authenticate future
|
|
requests to the identity server with.
|
|
required: ['token']
|
|
"/account":
|
|
get:
|
|
summary: Gets account holder information for a given token.
|
|
description: |-
|
|
Gets information about what user owns the access token used in the request.
|
|
operationId: getAccount
|
|
security:
|
|
- accessToken: []
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: The token holder's information.
|
|
examples:
|
|
application/json: {
|
|
"user_id": "@alice:example.org"
|
|
}
|
|
schema:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: string
|
|
description: The user ID which registered the token.
|
|
required: ['user_id']
|
|
403:
|
|
description: |
|
|
The user must do something in order to use this endpoint. One example
|
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_TERMS_NOT_SIGNED",
|
|
"error": "Please accept our updated terms of service before continuing"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
"/account/logout":
|
|
post:
|
|
summary: Logs out an access token, rendering it unusable.
|
|
description: |-
|
|
Logs out the access token, preventing it from being used to authenticate
|
|
future requests to the server.
|
|
operationId: logout
|
|
security:
|
|
- accessToken: []
|
|
parameters: []
|
|
responses:
|
|
200:
|
|
description: The token was successfully logged out.
|
|
examples:
|
|
application/json: {}
|
|
schema:
|
|
type: object
|
|
401:
|
|
description: |-
|
|
The token is not registered or is otherwise unknown to the server.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_UNKNOWN_TOKEN",
|
|
"error": "Unrecognised access token"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|
|
403:
|
|
description: |
|
|
The user must do something in order to use this endpoint. One example
|
|
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
|
|
examples:
|
|
application/json: {
|
|
"errcode": "M_TERMS_NOT_SIGNED",
|
|
"error": "Please accept our updated terms of service before continuing"
|
|
}
|
|
schema:
|
|
$ref: "../client-server/definitions/errors/error.yaml"
|