Account management

Register for an account on this homeserver.

This API endpoint uses the User-Interactive Authentication API, except in the cases where a guest account is being registered.

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.

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.

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.

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 MUST NOT use this endpoint when the server offers the m.login.sso authentication flow with oauth_aware_preferred set to true. Instead they MUST use the /login/sso/redirect endpoint, adding the action=register parameter.

post/_matrix/client/v3/register

Request

Base URL
https://matrix.org
Auth
none declared
TypeScript
https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/register/post.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

kind'guest' | 'user'

The kind of account to register. Defaults to user.

Request body

device_idstring

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_loginboolean

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_namestring

A display name to assign to the newly-created device. Ignored if device_id corresponds to a known device.

passwordstring

The desired password for the account.

refresh_tokenboolean

If true, the client supports refresh tokens.

usernamestring

The basis for the localpart of the desired Matrix ID. If omitted, the homeserver MUST generate a Matrix ID local part.

Example request

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "device_id": "GHTYAJCE",
  "initial_device_display_name": "Jungle Phone",
  "password": "ilovebananas",
  "username": "cheeky_monkey"
}

Response

The account has been registered.

access_tokenstring

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_idstring

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_msinteger

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_serverstring 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_tokenstring

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_idstring mx-user-id required

The fully-qualified Matrix user ID (MXID) that has been registered.