API Keys

Calling the http Web API requires one or more API keys. At lest one key should be created per application that will be calling the service.

API keys grant the caller the rights of the user account that they belong to, but with a reduced set of permissions to allow applications only the privileges that they need.

This helps to manage which applications have access to your devices, and removes the need to share your account credentials with external services.

Creating an API Key

API Keys can be created manually via the Portal web user interface, on the "API Keys" page.

To create a new API key:

  • Click the blue "New" button, to open the "Add New API Key" dialog.
  • Enter a recognisable Name (e.g the application or customer that this key is for), and optionally a Description.
  • Enable the permissions that you wish to grant to this key. For example enable "PrintToDevice" if this key should be allowed to send print jobs to the service. You can enable any permissions that are available to your account type.
  • Click the green "Add" button to create the key.

Applications can now use this key to access your device groups and devices, with the limited set of permissions that you have granted.

Calling the API using a Key

Each key is a hexadecimal characters sequence in GUID format. This sequence can be viewed/copied from the "API Keys" page of the web portal.

To call an API function, the key data should be passed in either via the key query option, or Star-Api-Key request header.

For example, to obtain a list of Device Groups under your account (using a key 6800ffd6-2367-4c8d-b067-d6a28151276a that has the ViewDeviceGroups permission), using the 'curl' command line utility:

pass key in the request header

curl --header "Star-Api-Key: 6800ffd6-2367-4c8d-b067-d6a28151276a" https://beta.starprinter/online/v1/a

or pass key as a query parameter

curl https://beta.starprinter/online/v1/a?key=6800ffd6-2367-4c8d-b067-d6a28151276a

Modifying a Key

An account owner can adjust the name, description or permissions granted to an API Key at any time from the "API Keys" portal page, by clicking the Edit button for that API Key.

Revoking/Deleting an API Key

API Keys can be revoked at any time by clicking the Delete button for that API key.

This will immediately disable access to your devices and Device Groups to any application authenticating via that key.

Warning

Deleting an API Key is permanent, it will not be possible to create a new key with the same character sequence. Any application using a deleted key will be completely unable to access the service until it is granted a new key.

Disabling a Key

It is possible to temporarily disable access to the API via a key, without removing the key entirely, but disabling all of its access permissions.