CreatBotMoonraker/docs/external_api/authorization.md

Authorization and Authentication

The Authorization endpoints provide access to the various methods used to authorize connections to Moonraker. This includes user authentication, API Key authentication, Temporary access via "oneshot tokens", and IP and/or domain based authentication ("ie: trusted clients).

Untrusted clients must use either a JSON Web Token or an API key to access Moonraker's HTTP APIs. JWTs should be included in the Authorization header as a Bearer type for each HTTP request. If using an API Key it should be included in the X-Api-Key header for each HTTP Request.

Websocket authentication can be achieved via the request itself or post connection. Unlike HTTP requests it is not necessary to pass a token and/or API Key to each request. The identify connection endpoint takes optional access_token and api_key parameters that may be used to authenticate a user already logged in, otherwise the login API may be used for authentication. Websocket connections will stay authenticated until the connection is closed or the user logs out.

User authentication can be performed using a choice sources. Moonraker currently supports the following authentication sources:

Source Name	Description
moonraker	Authentication is performed using credentials stored in
	Moonraker's database.
ldap	Authentication is performed through a connected LDAP provider.
	Requires a valid [LDAP] configuration.
{ #auth-source-desc } Authentication Source

/// note ECMAScript imposes limitations on certain requests that prohibit the developer from modifying the HTTP headers (ie: Requests to open a websocket, "download" requests that open a user dialog). In these cases it is recommended for the developer to request a oneshot_token, then send the result via the token query string argument in the desired request. ///

/// warning It is strongly recommended that arguments for the below APIs are passed in the request's body. ///

Login User

POST /access/login
Content-Type: application/json

{
    "username": "my_user",
    "password": "my_password",
    "source": "moonraker"
}

{
    "jsonrpc": "2.0",
    "method": "access.login",
    "params": {
        "username": "my_user",
        "password": "my_password",
        "source": "moonraker"
    },
    "id": 1323
}

/// api-parameters open: True

Name	Type	Default	Description
username	string	REQUIRED	The user login name.
password	string	REQUIRED	The user password.
source	string	Set by configuration	A valid authentication source.

///

/// collapse-code

{
    "username": "my_user",
    "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY4MDAuNDgxNjU1LCAiZXhwIjogMTYxODg4MDQwMC40ODE2NTUsICJ1c2VybmFtZSI6ICJteV91c2VyIiwgInRva2VuX3R5cGUiOiAiYXV0aCJ9.QdieeEskrU0FrH7rXKuPDSZxscM54kV_vH60uJqdU9g",
    "refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY4MDAuNDgxNzUxNCwgImV4cCI6IDE2MjY2NTI4MDAuNDgxNzUxNCwgInVzZXJuYW1lIjogIm15X3VzZXIiLCAidG9rZW5fdHlwZSI6ICJyZWZyZXNoIn0.btJF0LJfymInhGJQ2xvPwkp2dFUqwgcw4OA_wE-EcCM",
    "action": "user_logged_in",
    "source": "moonraker"
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The name of the logged in user.
token	string	A JSON Web Token (JWT) used to authenticate requests, also commonly
		referred to as an access token. HTTP requests should include this
		token in the Authorization header as a Bearer type. This token
		expires after 1 hour.
refresh_token	string	A JWT that should be used to generate new access tokens after they
		expire. See the refresh token section
		for details.
action	string	The action taken by the auth manager. Will always be
		"user_logged_in".
source	string	The authentication source used.

///

/// note This endpoint may be accessed without prior authentication. A 401 will only be returned if the authentication fails. ///

Logout Current User

POST /access/logout

{
    "jsonrpc": "2.0",
    "method": "access.logout",
    "id": 1323
}

/// collapse-code

{
    "username": "my_user",
    "action": "user_logged_out"
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The name of the logged out user.
action	string	The action taken by the auth manager. Will always be
		"user_logged_out".

///

Get Current User

GET /access/user

{
    "jsonrpc": "2.0",
    "method": "access.get_user",
    "id": 1323
}

Returns: An object containing the currently logged in user name, the source and the date on which the user was created (in unix time). /// collapse-code

{
    "username": "my_user",
    "source": "moonraker",
    "created_on": 1618876783.8896716
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The name of the logged in user.
source	string	The source used to authenticate
		the user.
created_on	float	The date, in unix time, the user entry was created.

///

Create User

Creates a new local user and logs them in.

POST /access/user
Content-Type: application/json

{
    "username": "my_user",
    "password": "my_password"
}

{
    "jsonrpc": "2.0",
    "method": "access.post_user",
    "params": {
        "username": "my_user",
        "password": "my_password"
    },
    "id": 1323
}

/// api-parameters open: True

Name	Type	Default	Description
username	string	REQUIRED	The user login name.
password	string	REQUIRED	The user password.

///

/// collapse-code

{
    "username": "my_user",
    "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY3ODMuODkxNjE5LCAiZXhwIjogMTYxODg4MDM4My44OTE2MTksICJ1c2VybmFtZSI6ICJteV91c2VyIiwgInRva2VuX3R5cGUiOiAiYXV0aCJ9.oH0IShTL7mdlVs4kcx3BIs_-1j0Oe-qXezJKjo-9Xgo",
    "refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzY3ODMuODkxNzAyNCwgImV4cCI6IDE2MjY2NTI3ODMuODkxNzAyNCwgInVzZXJuYW1lIjogIm15X3VzZXIiLCAidG9rZW5fdHlwZSI6ICJyZWZyZXNoIn0.a6ZeRjk8RQQJDDH0JV-qGY_d_HIgfI3XpsqUlUaFT7c",
    "source": "moonraker",
    "action": "user_created"
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The name of the created user.
token	string	A JSON Web Token (JWT) used to authenticate requests, also commonly
		referred to as an access token. HTTP requests should include this
		token in the Authorization header as a Bearer type. This token
		expires after 1 hour.
refresh_token	string	A JWT that should be used to generate new access tokens after they
		expire. See the refresh token section
		for details.
action	string	The action taken by the auth manager. Will always be "user_created".
source	string	The authentication source used.

///

/// note Unlike /access/login, /access/user is a protected endpoint. To create a new user a client must either be trusted, use the API Key, or be logged in as another user. ///

Delete User

/// note A request to delete a user MUST come from an authorized login other than the account to be deleted. This can be a "trusted user", the "api key user", or any other user account. ///

DELETE /access/user
Content-Type: application/json

{
    "username": "my_username"
}

{
    "jsonrpc": "2.0",
    "method": "access.delete_user",
    "params": {
        "username": "my_username"
    },
    "id": 1323
}

/// api-parameters open: True

Name	Type	Default	Description
username	str	REQUIRED	The username of the entry to delete.

///

/// collapse-code

{
    "username": "my_user",
    "action": "user_deleted"
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The username of the deleted entry.
action	string	The action taken by the auth manager. Will always
		be "user_deleted".

///

List Available Users

GET /access/users/list

{
    "jsonrpc": "2.0",
    "method": "access.users.list",
    "id": 1323
}

/// collapse-code

{
    "users": [
        {
            "username": "testuser",
            "source": "moonraker",
            "created_on": 1618771331.1685035
        },
        {
            "username": "testuser2",
            "source": "ldap",
            "created_on": 1620943153.0191233
        }
    ]
}

///

/// api-response-spec open: True

Field	Type	Description
users	[object]	An array of User Info objects.
		#user-info-spec

Field	Type	Description
username	string	The username of the entry.
source	string	The source that must be used to
		authenticate the user.
created_on	float	The date, in unix time, the user entry was created.
{ #user-info-spec } User Info

///

Reset User Password

POST /access/user/password
Content-Type: application/json

{
    "password": "my_current_password",
    "new_password": "my_new_pass"
}

{
    "jsonrpc": "2.0",
    "method": "access.user.password",
    "params": {
        "password": "my_current_password",
        "new_password": "my_new_pass"
    },
    "id": 1323
}

/// api-parameters open: True

Name	Type	Default	Description
password	string	REQUIRED	The user's current password.
new_password	string	REQUIRED	The user's new password.

///

/// collapse-code

{
    "username": "my_user",
    "action": "user_password_reset"
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The username of the entry whose password was reset.
action	string	Action taken by the Auth manager. Will always be
		"user_password_reset".

///

Refresh JSON Web Token

This endpoint can be used to refresh an expired access token. If this request returns an error then the refresh token is no longer valid and the user must login with their credentials.

POST /access/refresh_jwt
Content-Type: application/json

{
    "refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4Nzc0ODUuNzcyMjg5OCwgImV4cCI6IDE2MjY2NTM0ODUuNzcyMjg5OCwgInVzZXJuYW1lIjogInRlc3R1c2VyIiwgInRva2VuX3R5cGUiOiAicmVmcmVzaCJ9.Y5YxGuYSzwJN2WlunxlR7XNa2Y3GWK-2kt-MzHvLbP8"
}

{
    "jsonrpc": "2.0",
    "method": "access.refresh_jwt",
    "params": {
        "refresh_token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4Nzc0ODUuNzcyMjg5OCwgImV4cCI6IDE2MjY2NTM0ODUuNzcyMjg5OCwgInVzZXJuYW1lIjogInRlc3R1c2VyIiwgInRva2VuX3R5cGUiOiAicmVmcmVzaCJ9.Y5YxGuYSzwJN2WlunxlR7XNa2Y3GWK-2kt-MzHvLbP8"
    },
    "id": 1323
}

/// api-parameters open: True

Name	Type	Default	Description
refresh_token	string	REQUIRED	A valid refresh_token for the user.

///

/// collapse-code

{
    "username": "my_user",
    "token": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpc3MiOiAiTW9vbnJha2VyIiwgImlhdCI6IDE2MTg4NzgyNDMuNTE2Nzc5MiwgImV4cCI6IDE2MTg4ODE4NDMuNTE2Nzc5MiwgInVzZXJuYW1lIjogInRlc3R1c2VyIiwgInRva2VuX3R5cGUiOiAiYXV0aCJ9.Ia_X_pf20RR4RAEXcxalZIOzOBOs2OwearWHfRnTSGU",
    "source": "moonraker",
    "action": "user_jwt_refresh"
}

///

/// api-response-spec open: True

Field	Type	Description
username	string	The username of the entry whose access token ws refreshed.
token	string	A JSON Web Token (JWT) used to authenticate requests, also commonly
		referred to as an access token. HTTP requests should include this
		token in the Authorization header as a Bearer type. This token
		expires after 1 hour.
source	string	The authentication source of the user entry.
action	string	The action taken by the Auth Manager. Will always be
		"user_jwt_refresh".

///

/// note This endpoint may be accessed by unauthorized clients. A 401 will only be returned if the refresh token is invalid. ///

Generate a Oneshot Token

Javascript is not capable of modifying the headers for some HTTP requests (for example, the websocket), which is a requirement to apply JWT or API Key authorization. To work around this clients may request a Oneshot Token and pass it via the query string for these requests. Tokens expire in 5 seconds and may only be used once, making them relatively safe for inclusion in the query string.

GET /access/oneshot_token

{
    "jsonrpc": "2.0",
    "method": "access.oneshot_token",
    "id": 1323
}

"APDBEGHUTBUD6SOAYBPF3KE5BRMO7YSL"

/// api-response-spec open: True

The response is a string value containing the oneshot token. It may added to a request's query string for access to any API endpoint. The query string should be added in the form of:

?token={base32_random_token}

///

Get authorization module info

GET /access/info

{
    "jsonrpc": "2.0",
    "method": "access.info",
    "id": 1323
}

/// collapse-code

{
    "default_source": "moonraker",
    "available_sources": [
        "moonraker",
        "ldap"
    ],
    "login_required": false,
    "trusted": true
}

///

/// api-response-spec open: True

Field	Type	Description
default_source	string	The configured default
		authentication source.
available_sources	[string]	An array of available authentication sources.
login_required	bool	Set to true when force_logins is enabled via the
		configuration at least one user has been created.
trusted	bool	Set to true when the connection making the info
		request is a trusted connection.

///

/// note This endpoint may be accessed by unauthorized clients. ///

Get the Current API Key

GET /access/api_key

{
    "jsonrpc": "2.0",
    "method": "access.get_api_key",
    "id": 1323
}

e514851f37b94c779d955212b6906f95

/// api-response-spec open: True

The response string value containing the current API key.

///

Generate a New API Key

POST /access/api_key

{
    "jsonrpc": "2.0",
    "method": "access.post_api_key",
    "id": 1323
}

e514851f37b94c779d955212b6906f95

/// api-response-spec open: True

The response string value containing the new API key.

///

/// note After this request executes the API key change is applied immediately. All subsequent HTTP requests from untrusted clients must use the new key. Changing the API Key will not affect open websockets authenticated using the previous API Key. ///