Auth API

This is a reference page for the Actyx Auth API.

The Auth HTTP API generates auth tokens that are used to authenticate an app under a certain app ID with a node. You need to pass a valid token along each request to the Events API. In case you are using our SDK, you only have to supply the manifest, and the rest is automatically taken care of. Otherwise, please follow this guide to manually using the Auth API.

The Auth API is reachable at the following base URI: http://localhost:4454/api/v2/auth.

Pretty printed JSON

JSON used in the examples below is pretty-printed with jq. This is only to make it more readable here. In reality, the Auth API does not return pretty-printed JSON but the usual compact JSON you know from any other service.

For a detailed explanation of how authentication and authorization works with Actyx, please refer to the conceptual guide.

Generate an auth token

You can request an auth token from the Auth API in exchange for a valid JSON payload.

Request

• Endpoint: http://localhost:4454/api/v2/auth
• HTTP method: POST
• HTTP headers:
  • Content-Type, must be application/json

The request body must contain a JSON object with the following fields:

{
  "appId": "<string: app ID>",
  "displayName": "<string: display name>",
  "version": "<string: version>",
  "signature": "<string: signature>"
}

Required: App ID (appId)

The app ID of your app. Needs to be in reverse domain form. For trial usage, please use com.example.*, meaning you can put anything you like in place of the *.

Required: Display name (displayName)

The display name used to identify your app., e.g. My Awesome App.

Required: Version number (version)

The version number of your application, e.g. 2.0.0. Note that you can use any versioning scheme you like as the version number is an arbitrary string.

Signature (signature)

The manifest signature generated by the CLI or the Node Manager. The signature is a hashed string generated using the three values appID, displayName and version. Note that you only need to add a signature if you use your own namespace as app ID. If you use the app ID com.example.*, the signature is not required.

additional properties

You can add additional properties to your manifest at will. The only required ones are listed above.

Response

• HTTP headers:
  • Content-Type is application/x-ndjson

{
  "token": "<string: auth token>"
}

If an error is encountered while processing the request, the API will return an error JSON object of the following structure:

{
    "code": "<string: error code>",
    "message": "<string: error message>"
}

Example

See the following example using cURL:

Request

echo '
{
    "appId": "com.example.app",
    "displayName": "Example App",
    "version": "1.0.0"
}
' \
| curl \
    -s -X "POST" \
    -d @- \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    http://localhost:4454/api/v2/auth \
| jq .

Alternatively, you can directly pass in your manifest.json file:

Request

curl \
    -s -X "POST" \
    -d @manifest.json \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    http://localhost:4454/api/v2/auth \
| jq .

Response

{
  "token": "AAAAXaZnY3JlYXRlZBsABcIhKEY90mVhcHBJZG9jb20uZXhhbXBsZS5hcHBmY3ljbGVzAGphcHBWZXJzaW9uZTEuMC4waHZhbGlkaXR5GgABUYBnYXBwTW9kZWV0cmlhbAEuMkUrR1EHEC/ZPnOm5yCUZCOMwUGqP6UQLOC2r2xWr5ja9HC0KaYXfyQMaQmUcg7nA9BdwWe2KPUtETN1aqQTfeYDTOja38YXd32Ig9NOY39rg5H+ViDm6Lo0OXzYgwQ="
}