Search
⌃K

X-API Keys

PlaceOS can generate API Keys for authenticated access.
The API keys can be used for:

Prerequisites

  • Administrator access to your PlaceOS Backoffice

Generate API Key

  1. 1.
    Login to PlaceOS Backoffice
  2. 2.
    Navigate to the Admin Tab
  3. 3.
    Select API Keys ​
    Select API Keys from Admin Menu
    ​    ​
  4. 4.
    Select the domain the API Key will belong to
  5. 5.
    Any existing API Keys will be shown in the list
  6. 6.
    Click Add API Key ​
    Select API Keys from Admin Menu
    ​    ​
  7. 7.
    Enter the required information:
    • Name: Suitable name for the API Key
    • Description: What the key will be used for (useful for other administrators)
    • Scopes: Select from available scopes (see available scopes below)
    • User: The user in which the API Key will emulate
    • Permissions: Permission level assigned to the API Key (see permission details below) ​
      Add new API Key Form
      ​      ​
  8. 8.
    Click Save
  9. 9.
    The new API Key will be shown once after it is saved, you will not be able to view it again ​
    Showing the new API Key
    ​    ​

Available Scopes

Available Scopes for API Keys are:
  • public A special scope that can access all routes (supports read and write modifiers)
  • api_keys
  • ldap_authentication
  • saml_authentication
  • o_auth_authentication
  • o_auth_applications
  • brokers
  • cluster
  • domains
  • drivers
  • settings
  • modules
  • guests A special scope for guests that provides access to some APIs​
  • systems
  • control .read: module class types, function list of a module, module state lookup .write: control websocket, API execute request
  • edges
  • metadata
  • repositories

Available Permissions

  • scope.read
  • scope.write

Using the API Key

API Keys are typically passed in the header of the request, however can be used in the following ways
  1. 1.
    HTTP Header: X-API-Key: <token>
  2. 2.
    URL param: ?api-key=<token>
  3. 3.
    A HTTP Cookie: api-key=<token>

Removing an API Key

  1. 1.
    Navigate to the API Key Page in Backoffice located in the Admin Tab.
  2. 2.
    Click the trash icon to remove the key. ​
    Remove API Key
    ​    ​
Previous
Configure OAuth2 SSO
Next
Bearer tokens
Last modified 5mo ago