Skip to main content

Authentication and authorization

This guide explains authentication and authorization with Actyx. In general, the auth concepts are either related to:

  • user auth for administrative access to a node or
  • app auth for access to the Events API of a node.

Administrative access​

Administrative access to a node is based on two different concepts:

  1. User authentication with user keys
  2. User authorization through node settings

User authentication​

You can authenticate with a key pair consisting of a private and public key. The key pair is stored on your computer and can be created with the Actyx CLI or Node Manager. Every interaction between CLI or Node Manager and a node requires you to authenticate with your keys. By default, the CLI or Node Manager uses the keys in the default storage path, but you can also specify a different path.

User authorization​

If your keys are not authorized to manage the node, it rejects the command and you receive an error with code ERR_UNAUTHORIZED. The authorized users of a node can be managed in the node setting /admin/authorizedUsers. authorizedUsers is an array that contains all public keys of users that are authorized to manage the node. If authorizedUsersis empty (e.g. after you start a node for the first time), the first user to interact with a node is automatically added as an authorized user. You can find a how-to guide for configuring authorizedUsers here.

Auth for access to the Events API​

Accessing a node's Events API is based on three different concepts:

  1. Developer authorization with a developer certificate
  2. App authentication using a signed app manifest
  3. App authorization with app license keys
working with Actyx during development

Note that this guide only is relevant for you if you are preparing an app to run in production. If you simply want to try out Actyx and use the APIs for development purposes only, please use an app ID starting with com.example. The rest will be taken care of by Actyx.

Developer authorization​

All events emitted by an app are linked to its app ID. Therefore, you need to be authorized to develop apps that use a certain app ID. For proving this, you need an Actyx developer certificate which contains information about the app IDs you are authorized to use. It is generated by Actyx and can be obtained by filling out this form.

info

If you want to receive a developer certificate, please enter your email address in this form and we will send you one within 24 hours.

authentication-01

The app IDs that a developer certificate allows you to use are linked to the domain name of your email address that was used for generating the developer certificate. App IDs must be lowercase and written in reverse domain name notation (and valid as DNS names, i.e. consist of ASCII letters, digits, and dashes), so, for example, if your work email address is [email protected], your developer certificate allows you to sign apps that start with com.awesome-si.. After that, you then typically add the name of your app, e.g. com.awesome-si.dashboard-app.

Once you have received your developer certificate, please make sure to save it in a secure location on your device as you will need to provide the path to your certificate every time you want to sign an app manifest. As this certificate is linked to the domain of your e-mail address, you may also share the certificate with your colleagues to allow them to use it for app signing as well.

App Authentication​

Every request of your app to the Events API must be sent with a valid auth token. In order to get an auth token from the Auth API, your app must authenticate. This is done by providing the node with a signed manifest using the Auth API or our SDK. That way, the events that are emitted by the signed app can be correctly associated with its app ID. This also guarantees that events with that app ID cannot be published by other apps with different app IDs.

You can sign your manifest by providing the CLI or the Node Manager with the path to your developer certificate and the path to your manifest.

authentication-02

In return for a valid, signed manifest you will receive an auth token. This token must then be used with every HTTP request to the Events API.

info

For a detailed guide on how to sign a manifest or authenticate an app, please refer to our how-to guides on app signing and app authentication.

App Authorization​

For receiving an auth token, apps must not only be authenticated but also authorized. You can authorize apps by providing a valid app license key. Please get in touch with your contact at Actyx or fill out this form for buying app licenses. Once you have obtained an app license, simply add the license key to the settings on the node on which you want to run the app.

No need for licenses during development

If you are working with an Actyx node in development, apps running on that node do not need to be licensed. In that case, please configure your node to be in development:

Node settings example
...
"licensing": {
    "node": "development"
}
...