--- title: "Register for an account on this homeserver." method: POST path: "/_matrix/client/v3/register" tags: ["Account management"] --- # Register for an account on this homeserver. `POST /_matrix/client/v3/register` ## Request - Base URL: `https://matrix.org` - URL: `https://matrix.org/_matrix/client/v3/register` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api), except in the cases where a guest account is being registered. Register for an account on this homeserver. There are two kinds of user account: - `user` accounts. These accounts may use the full API described in this specification. - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers. If registration is successful, this endpoint will issue an access token the client can use to authorise itself in subsequent requests. If the client does not supply a `device_id`, the server must auto-generate one. The server SHOULD register an account with a User ID based on the `username` provided, if any. Note that the grammar of Matrix User ID localparts is restricted, so the server MUST either map the provided `username` onto a `user_id` in a logical manner, or reject any `username` which does not comply to the grammar with `M_INVALID_USERNAME`. Matrix clients MUST NOT assume that localpart of the registered `user_id` matches the provided `username`. 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). When registering a guest account, all parameters in the request body with the exception of `initial_device_display_name` MUST BE ignored by the server. The server MUST pick a `device_id` for the account regardless of input. Any user ID returned by this API must conform to the grammar given in the [Matrix specification](https://spec.matrix.org/v1.19/appendices/#user-identifiers). **NOTE:** **[Added in `v1.17`]** Even if the server doesn't support the Legacy authentication API, it MUST support this endpoint for application services to be able to [create users](https://spec.matrix.org/v1.19/application-service-api/#server-admin-style-permissions). In that case application services MUST set the `"inhibit_login": true` parameter as they cannot use it to log in as users. If the `inhibit_login` parameter is not set to `true`, the server MUST return a 400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code. **WARNING:** **[Added in `v1.18`]** [OAuth 2.0 aware clients](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-aware-clients) MUST NOT use this endpoint when the server offers the [`m.login.sso` authentication flow](https://spec.matrix.org/v1.19/client-server-api/#client-login-via-sso) with `oauth_aware_preferred` set to `true`. Instead they MUST use the [`/login/sso/redirect`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3loginssoredirect) endpoint, adding the `action=register` parameter. ## Query parameters - `kind` 'guest' | 'user' ## Request body - object - `auth` object: Used by clients to submit authentication information to the interactive-authentication API - `session` string: The value of the session key given by the homeserver. - `type` string: The authentication type that the client is attempting to complete. May be omitted if `session` is given, and the client is reissuing a request which it believes has been completed out-of-band (for example, via the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)). - `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 server will auto-generate a `device_id` if this is not specified. - `inhibit_login` boolean: If true, an `access_token` and `device_id` should not be returned from this call, therefore preventing an automatic login. Defaults to `false`. - `initial_device_display_name` string: A display name to assign to the newly-created device. Ignored if `device_id` corresponds to a known device. - `password` string: The desired password for the account. - `refresh_token` boolean: If `true`, the client supports refresh tokens. - `username` string: The basis for the localpart of the desired Matrix ID. If omitted, the homeserver MUST generate a Matrix ID local part. ## Response `200` The account has been registered. - object - `access_token` string: An access token for the account. This access token can then be used to authorise other requests. Required if the `inhibit_login` option is false. - `device_id` string: ID of the registered device. Will be the same as the corresponding parameter in the request, if one was specified. Required if the `inhibit_login` option is false. - `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. Omitted if the `inhibit_login` option is true. - `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. Omitted if the `inhibit_login` option is true. - `user_id` string, mx-user-id, required: The fully-qualified Matrix user ID (MXID) that has been registered. Any user ID returned by this API must conform to the grammar given in the [Matrix specification](https://spec.matrix.org/v1.19/appendices/#user-identifiers). ## Other responses - `400`: 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_INVALID_USERNAME` : The desired user ID is not a valid user name. * `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace claimed by an application service. * **[Added in `v1.17`]** `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service used the `m.login.application_service` type without setting `inhibit_login` to `true`, but the server doesn't support logging in via the Legacy authentication API. 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. Homeservers 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. - `401`: The homeserver requires additional authentication information. - `403`: The homeserver does not permit registering the account. This response can be used to identify that a particular `kind` of account is not allowed, or that registration is generally not supported by the homeserver. - `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)