powersync-docs/docs/api/metier/jsonrpc.md

JSONRPC

Methods

JSONRPC.Authenticate

AUTH

Authenticate a client to the api via user & password challenge. Provide a device name which allows the user to identify the client and revoke the token in case the device is lost or stolen. This will return a new token to be used to authorize a client at the API.

Parameters:

Field	Type	Notes
deviceName	String
password	String
username	String

Returns:

Field	Type	Notes
scopes	PermissionScopes	optional
token	String	optional
username	String	optional
success	Bool

---

JSONRPC.CreateUser

ADMIN

Create a new user in the API. This is only allowed to be called when the initial setup is required. To create additional users, use Users.CreateUser instead. Call Authenticate after this to obtain a device token for the newly created user.

Parameters:

Field	Type	Notes
displayName	String	optional
email	String	optional
password	String
username	String

Returns:

Field	Type	Notes
error	UserError

---

JSONRPC.Hello

AUTH

Initiates a connection. Use this method to perform an initial handshake of the connection. Optionally, a parameter "locale" is can be passed to set up the used locale for this connection. Strings such as ThingClass displayNames etc will be localized to this locale. If this parameter is omitted, the default system locale (depending on the configuration) is used. The reply of this method contains information about this core instance such as version information, uuid and its name. The locale valueindicates the locale used for this connection. Note: This method can be called multiple times. The locale used in the last call for this connection will be used. Other values, like initialSetupRequired might change if the setup has been performed in the meantime. The field cacheHashes may contain a map of methods and MD5 hashes. As long as the hash for a method does not change, a client may use a previously cached copy of the call instead of fetching the content again. While the Hello call doesn't necessarily require a token, this can be called with a token. If a token is provided, it will be verified and the reply contains information about the tokens validity and the user and permissions for the given token.

Parameters:

Field	Type	Notes
locale	String	optional

Returns:

Field	Type	Notes
authenticationRequired	Bool
initialSetupRequired	Bool
language	String
locale	String
name	String
authenticated	Bool	optional
cacheHashes	CacheHash[]	optional
experiences	Experience[]	optional
permissionScopes	PermissionScopes	optional
username	String	optional
protocol version	String
pushButtonAuthAvailable	Bool
server	String
uuid	Uuid
version	String

---

JSONRPC.Introspect

AUTH

Introspect this API.

Parameters:

No parameters.

Returns:

Field	Type	Notes
methods	Object
notifications	Object
types	Object

---

JSONRPC.KeepAlive

AUTH

This is basically a Ping/Pong mechanism a client app may use to check server connectivity. Currently, the server does not actually do anything with this information and will return the call providing the given sessionId back to the caller. It is up to the client whether to use this or not and not required by the server to keep the connection alive.

Parameters:

Field	Type	Notes
sessionId	String

Returns:

Field	Type	Notes
sessionId	String
success	Bool

---

JSONRPC.RequestPushButtonAuth

AUTH

Authenticate a client to the api via Push Button method. Provide a device name which allows the user to identify the client and revoke the token in case the device is lost or stolen. If push button hardware is available, this will return with success and start listening for push button presses. When the push button is pressed, the PushButtonAuthFinished notification will be sent to the requesting client. The procedure will be cancelled when the connection is interrupted. If another client requests push button authentication while a procedure is still going on, the second call will take over and the first one will be notified by the PushButtonAuthFinished signal about the error. The application should make it clear to the user to not press the button when the procedure fails as this can happen for 2 reasons: a) a second user is trying to auth at the same time and only the currently active user should press the button or b) it might indicate an attacker trying to take over and snooping in for tokens.

Parameters:

Field	Type	Notes
deviceName	String

Returns:

Field	Type	Notes
success	Bool
transactionId	Int

---

JSONRPC.SetNotificationStatus

AUTH

Enable/Disable notifications for this connections. Either "enabled" or "namespaces" needs to be given but not both of them. The boolean based "enabled" parameter will enable/disable all notifications at once. If instead the list-based "namespaces" parameter is provided, all given namespaceswill be enabled, the others will be disabled. The return value of "success" will indicate success of the operation. The "enabled" property in the return value is deprecated and used for legacy compatibilty only. It will be set to true if at least one namespace has been enabled.

Parameters:

Field	Type	Notes
d:o:enabled	Bool
namespaces	StringList	optional

Returns:

Field	Type	Notes
d:enabled	Bool
namespaces	StringList

---

JSONRPC.Version

AUTH

Version of this nymea/JSONRPC interface.

Parameters:

No parameters.

Returns:

Field	Type	Notes
protocol version	String
qtBuildVersion	String
qtVersion	String
version	String

---

Notifications

JSONRPC.PushButtonAuthFinished

Emitted when a push button authentication reaches final state. NOTE: This notification is special. It will only be emitted to connections that did actively request a push button authentication, but also it will be emitted regardless of the notification settings.

Parameters:

Field	Type	Notes
token	String	optional
success	Bool
transactionId	Int

---