Register an application in OpenPlatform

OpenPlatform · openplatform@5 openplatformappstokenssetup

An application is a record that the administrator creates in the setup screen (/setup/, the apps API of the setup plugin). The record is the contract between OpenPlatform and your application: where it lives, how the two of them prove who they are, and what the user may do in it. The schema of the record is @Apps in plugins/setup/schemas/apps.js.

Field	Required	Meaning
`name`	yes	the name shown in the portal
`url`	yes	the address that OpenPlatform opens
`reqtoken`	yes	a secret that you choose and that both sides know: it signs the request
`restoken`	yes	a second secret, also shared: the application uses it to sign its answer
`color`, `icon`	no	how the application looks in the portal
`meta`	no	an address (URL) that returns the metadata of the application: the setup screen can download it (`Apps/download`) to fill in the record
`sortindex`	no	the order in the list (a new application goes to the end)
`notifications`	no	whether the application may send notifications
`isexternal`	no	the application is not opened inside the portal's frame: the answer to the application says `iframe: false`
`isbookmark`	no	the application is a plain link: no token handshake, only a session identifier in the query string
`isnewtab`	no	open it in a new browser tab instead of the frame of the portal (the setting `newtab` does it for every application)
`isscrollbar`	no	the frame of the application in the portal keeps its scrollbar (the portal sets `scrolling` to `yes` or `no`)
`isdisabled`	no	switch it off for everybody: the user gets "App has been temporary disabled"
`permissions`	no	the list of permissions of the application: each one has an `id`, a `name` and a `value` (see groups and permissions)

The table tbl_app also has a column allow ("allows only specific IP addresses"): when it holds addresses, the application can call the protocol endpoints of OpenPlatform only from them. The setup schema above does not list it, so it is a database column that you fill in directly.

The two tokens

reqtoken and restoken are never sent to the browser. OpenPlatform derives from them, for each launch, the values that travel: the token in the address of the application and the header that the application sends back. The derivation is in how an app connects. Use long random values and a different pair for each application.

Removing and changing

An application is never deleted from the table: removing it (Apps/remove) sets isremoved and the date of the removal, clears the cache of the users that had it, and isdisabled switches it off without removing it. When the address of the platform (the url setting) changes, OpenPlatform clears the notification links of every user and deletes the open application sessions, because both contain that address (settings and database).

Remember the rule of the README: a registered application is visible to nobody until a group is assigned to it.