Skip to main content

Authenticate with app manifest


This guide is part of a series about running your own Actyx deployment in production. If you haven't done so, we strongly encourage you to read the previous guide!

If you're still testing Actyx or developing your application, set the node licensing to development in the node settings.

"licensing": {
"node": "development"

In order for your app to access the Events API, it needs to be authenticated with the node it is running on. This how-to guide explains the steps you need to take to authenticate your app with a node. You can authenticate your app using our Typescript SDK (recommended) or by manually using the Auth API. For this guide, let's use the following my-manifest.json as an example:

"appId": "com.actyx.example",
"displayName": "Example App",
"version": "2.0",
"signature": "v2tzaWdfdmVyc2lvbgBtZGV2X3NpZ25hdHVyZXhYMTdNQkpYTGVhM3VzTC94RFQ1dWM3bW53c2pyWnhNdGVZeUxSWUdCQzh6VitFTm1tQ0ZkQjRCOCtSeTNQSDNHN2haNEt0NE80eXpMSEdFT3J5blpVQ3c9PWlkZXZQdWJrZXl4LTA0T2dDSkFYSFU5bnRjbkpnaXl2NnFJbmtYUGg0MG5DcFJiS0tJcXVuckJNPWphcHBEb21haW5zgWtjb20uYWN0eXguKmtheFNpZ25hdHVyZXhYUWwyaU5MQjRmbHlCYWFhWHhMRUF0RzZhbzlUWlpJTVFVaDlSL2poNXNzVVRQNHR5d3RRcjIvZitXR2FWSHdlQ0xhVnVDY3JDOWdTVE0zSnRqZFA4QWc9Pf8="

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).

The SDK automatically manages the authentication flow for the application. It only needs to be provided with the signed manifest upon initialization. It then does two things automatically:

  • Upon initialization, it gets a token from the Auth API or fails with an error.
  • It deals with expired token responses, and will automatically try to get a new token from the Auth API. If the token is not renewed, it fails with an error.

See an example below of how to initialize the SDK with the signed manifest.

import { Actyx } from '@actyx/sdk'
const manifest = require('my-manifest.json')

try {
// pass in manifest as first argument
// second argument is optional
const actyx = await Actyx.of(manifest, connectionOpts)
} catch (error) {

If you want to read a more holistic explanation of authentication and authorization with Actyx, please check out our conceptual guide on the topic.