--- title: "Authenticates the user." method: POST path: "/_matrix/client/v3/login" tags: ["Session management"] --- # Authenticates the user. `POST /_matrix/client/v3/login` ## Request - Base URL: `https://matrix.org` - URL: `https://matrix.org/_matrix/client/v3/login` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Authenticates the user, and issues an access token they can use to authorise 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](https://spec.matrix.org/v1.19/client-server-api/#relationship-between-access-tokens-and-devices). ## Request body - object - `address` string: Third-party identifier for the user. Deprecated in favour of `identifier`. - `device_id` string: 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](https://spec.matrix.org/v1.19/client-server-api/#cross-signing) key ID. The server will auto-generate a `device_id` if this is not specified. - `identifier` object: Identification information for a user - `type` string, required: The type of identification. See [Identifier types](https://spec.matrix.org/v1.19/client-server-api/#identifier-types) for supported values and additional property descriptions. - `initial_device_display_name` string: A display name to assign to the newly-created device. Ignored if `device_id` corresponds to a known device. - `medium` string: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. - `password` string: Required when `type` is `m.login.password`. The user's password. - `refresh_token` boolean: If true, the client supports refresh tokens. - `token` string: Required when `type` is `m.login.token`. Part of Token-based login. - `type` string, required: The login type being used. This must be a type returned in one of the flows of the response of the [`GET /login`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3login) endpoint, like `m.login.password` or `m.login.token`. - `user` string: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. ## Response `200` The user has been authenticated. - object - `access_token` string, required: An access token for the account. This access token can then be used to authorise other requests. - `device_id` string, required: ID of the logged-in device. Will be the same as the corresponding parameter in the request, if one was specified. - `expires_in_ms` integer: 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. - `home_server` string, mx-server-name: 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. - `refresh_token` string: 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. - `user_id` string, mx-user-id, required: The fully-qualified Matrix ID for the account. - `well_known` object: Used by clients to determine the homeserver, identity server, and other optional components they should be interacting with. - `m.homeserver` object, required: Used by clients to discover homeserver information. - `base_url` string, uri, required: The base URL for the homeserver for client-server connections. - `m.identity_server` object: Used by clients to discover identity server information. - `base_url` string, uri, required: The base URL for the identity server for client-server connections. ## Other responses - `400`: Part of the request was invalid. For example, the login type may not be recognised. Specific error codes used with this status code include: * **[Added in `v1.17`]** `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service used the `m.login.application_service` type, but the server doesn't support logging in via the Legacy authentication API. - `403`: 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. Servers MAY instead use `M_FORBIDDEN` when they can no longer authenticate the deactivated user (e.g. their password has been wiped). - `429`: This request was rate-limited. --- [API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)