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:

Authentication Source
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.

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.

HTTP Request

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

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

JSON-RPC Request

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

Parameters

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.

Example Response

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

Response Specification

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¶

HTTP Request

POST /access/logout

JSON-RPC Request

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

Example Response

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

Response Specification

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¶

HTTP Request

GET /access/user

JSON-RPC Request

{
    "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).

Example Response

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

Response Specification

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.

HTTP Request

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

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

JSON-RPC Request

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

Parameters

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

Example Response

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

Response Specification

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.

HTTP Request

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

{
    "username": "my_username"
}

JSON-RPC Request

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

Parameters

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

Example Response

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

Response Specification

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¶

HTTP Request

GET /access/users/list

JSON-RPC Request

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

Example Response

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

Response Specification

Field Type Description

users [object] An array of User Info objects.

User Info
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.

Reset User Password¶

HTTP Request

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

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

JSON-RPC Request

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

Parameters

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

Example Response

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

Response Specification

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.

HTTP Request

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

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

JSON-RPC Request

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

Parameters

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

Example Response

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

Response Specification

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.

HTTP Request

GET /access/oneshot_token

JSON-RPC Request

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

Example Response

"APDBEGHUTBUD6SOAYBPF3KE5BRMO7YSL"

Response Specification

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¶

HTTP Request

GET /access/info

JSON-RPC Request

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

Example Response

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

Response Specification

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¶

HTTP Request

GET /access/api_key

JSON-RPC Request

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

Example Response

e514851f37b94c779d955212b6906f95

Response Specification

The response string value containing the current API key.

Generate a New API Key¶

HTTP Request

POST /access/api_key

JSON-RPC Request

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

Example Response

e514851f37b94c779d955212b6906f95

Response Specification

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.

Authorization and Authentication¶

Login User¶

Logout Current User¶

Get Current User¶

Create User¶

Delete User¶

List Available Users¶

Reset User Password¶

Refresh JSON Web Token¶

Generate a Oneshot Token¶

Get authorization module info¶

Get the Current API Key¶

Generate a New API Key¶