Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 21:14:09 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity
matrix-spec/data/api/client-server/login.yaml

337 lines
14 KiB
YAML
Raw Blame History

# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
# Copyright 2022 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 Client-Server Registration and Login API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v3
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/login":
get:
summary: Get the supported login types to authenticate users
description: |-
Gets the homeserver's supported login types to authenticate users. Clients
should pick one of these and supply it as the `type` when logging in.
operationId: getLoginFlows
responses:
200:
description: The login types the homeserver supports
examples:
application/json: {
"flows": [
{"type": "m.login.password"},
{"type": "m.login.token", "get_login_token": true}
]
}
schema:
type: object
properties:
flows:
type: array
description: The homeserver's supported login types
items:
type: object
title: LoginFlow
required: ['type']
properties:
type:
description: |-
The login type. This is supplied as the `type` when
logging in.
type: string
get_login_token:
type: boolean
x-addedInMatrixVersion: "1.7"
description: |-
If `type` is `m.login.token`, an optional field to indicate
to the unauthenticated client that the homeserver supports
the `POST /login/get_token` endpoint. Note that supporting
the endpoint does not necessarily indicate that the user
attempting to log in will be able to generate such a token.
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management
post:
summary: Authenticates the user.
description: |-
Authenticates the user, and issues an access token they can
use to authorize themself in subsequent requests.
If the client does not supply a `device_id`, the server must
auto-generate one.
The returned access token must be associated with the `device_id`
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
[Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices).
operationId: login
parameters:
- in: body
name: body
required: true
schema:
type: object
example: {
"type": "m.login.password",
"identifier": {
"type": "m.id.user",
"user": "cheeky_monkey"
},
"password": "ilovebananas",
"initial_device_display_name": "Jungle Phone"
}
properties:
type:
type: string
enum: ["m.login.password", "m.login.token"]
description: The login type being used.
identifier:
"$ref": "definitions/user_identifier.yaml"
user:
type: string
description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`.
medium:
type: string
description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`.
address:
type: string
description: Third-party identifier for the user. Deprecated in favour of `identifier`.
password:
type: string
description: |-
Required when `type` is `m.login.password`. The user's
password.
token:
type: string
description: |-
Required when `type` is `m.login.token`. Part of Token-based login.
device_id:
type: string
description: |-
ID of the client device. If this does not correspond to a
known client device, a new device will be created. The given
device ID must not be the same as a
[cross-signing](/client-server-api/#cross-signing) key ID.
The server will auto-generate a device_id
if this is not specified.
initial_device_display_name:
type: string
description: |-
A display name to assign to the newly-created device. Ignored
if `device_id` corresponds to a known device.
refresh_token:
type: boolean
description: |-
If true, the client supports refresh tokens.
x-addedInMatrixVersion: "1.3"
required: ["type"]
responses:
200:
description: The user has been authenticated.
examples:
application/json: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"refresh_token": "def456",
"expires_in_ms": 60000,
"device_id": "GHTYAJCE",
"well_known": {
"m.homeserver": {
"base_url": "https://example.org"
},
"m.identity_server": {
"base_url": "https://id.example.org"
}
}
}
schema:
type: object
properties:
user_id:
type: string
description: The fully-qualified Matrix ID for the account.
access_token:
type: string
description: |-
An access token for the account.
This access token can then be used to authorize other requests.
refresh_token:
type: string
description: |-
A refresh token for the account. This token can be used to
obtain a new access token when it expires by calling the
`/refresh` endpoint.
x-addedInMatrixVersion: "1.3"
expires_in_ms:
type: integer
description: |-
The lifetime of the access token, in milliseconds. Once
the access token has expired a new access token can be
obtained by using the provided refresh token. If no
refresh token is provided, the client will need to re-log in
to obtain a new access token. If not given, the client can
assume that the access token will not expire.
x-addedInMatrixVersion: "1.3"
home_server:
type: string
description: |-
The server_name of the homeserver on which the account has
been registered.
**Deprecated**. Clients should extract the server_name from
`user_id` (by splitting at the first colon) if they require
it. Note also that `homeserver` is not spelt this way.
device_id:
type: string
description: |-
ID of the logged-in device. Will be the same as the
corresponding parameter in the request, if one was specified.
well_known:
description: |-
Optional client configuration provided by the server. If present,
clients SHOULD use the provided object to reconfigure themselves,
optionally validating the URLs within. This object takes the same
form as the one returned from .well-known autodiscovery.
allOf:
- "$ref": "definitions/wellknown/full.yaml"
required: ["access_token", "device_id", "user_id"]
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The login attempt failed. This can include one of the following error codes:
* `M_FORBIDDEN`: The provided authentication data was incorrect
or the requested device ID is the same as a cross-signing key
ID.
* `M_USER_DEACTIVATED`: The user has been deactivated.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management
"/login/get_token":
post:
summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token.
description: |-
Optional endpoint - the server is not required to implement this endpoint if it does not
intend to use or support this functionality.
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
An already-authenticated client would call this endpoint to generate a single-use, time-limited,
token for an unauthenticated client to log in with, becoming logged in as the same user which
called this endpoint. The unauthenticated client uses the generated token in a `m.login.token`
login flow with the homeserver.
Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes
this feature if the server is not offering it. Authenticated clients can check for support on
a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation),
while unauthenticated clients can detect server support by looking for an `m.login.token` login
flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login).
In v1.7 of the specification, transmission of the generated token to an unauthenticated client is
left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906)
might standarise a way to transmit the token between clients.
The generated token MUST only be valid for a single login, enforced by the server. Clients which
intend to log in multiple devices must generate a token for each.
With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt
for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt
the user for verification to ensure explicit consent is gained for each additional client.
Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum
of 1 request per minute.
operationId: generateLoginToken
x-addedInMatrixVersion: "1.7"
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
description: An empty JSON object.
responses:
200:
description: The login token an unauthenticated client can use to log in as the requesting user.
examples:
application/json: {
"login_token": "<opaque string>",
"expires_in_ms": 120000
}
schema:
type: object
required: ["login_token", "expires_in_ms"]
properties:
login_token:
type: string
description: The login token for the `m.login.token` login flow.
expires_in_ms:
type: integer
description: |-
The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
(2 minutes) is recommended as a default.
400:
description: |-
The request was malformed, or the user does not have an ability to generate tokens for their devices,
as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token`
[capability](/client-server-api/#capabilities-negotiation).
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management
Reference in a new issue View git blame Copy permalink