Token Authentication

API Tokens are used to authorize invokes of Workflows via REST API.

Creating and Managing Tokens

You can access the API Keys Pane from the left-hand menu.

Click + to generate a new API Key.

Name

Provides a unique name for the key. When a invoked using a key, the InitialisationXml Property included in the Start Node Workflow Log will indicate the key that was used in the form Token-based Key: your-key-name in the Username element.

Enabled

Keys can be disabled as necessary. Note that it may take up to five minutes for a disabled key to stop working.

Target Site Environment

Select the Site Environment that will be used when a Workflow is invoked via API key. It is not possible to share API keys across Site Environments.

Primary and Secondary Keys

Contains the generated keys. Note that these keys are only available when first generated. If a key is lost it will be necessary to regenerate it and all consumers relying on the old key must be updated to use the new key.

Permitted Workflows

Select the Workflows that will be permitted to execute against this Key. Note that only Workflows that are bound to a REST template are displayed in this list. The API Key cannot be used to invoke Workflows that are not specified here.

Specifying a Key in an API call

API Keys can be provided via a querystring or via the Authorization HTTP Header.

Providing a Key in the HTTP Authorization Header (recommended)

Add the following header to your request:

Authorization: Key=your-auth-key

Providing a Key in the URL querystring (not recommended)

Append the querystring auth-key to the request URL. For example, if you are invoking this Workflow:

https://mycompany.flowgear.net/customers/123/

Provide the API Key like this:

https://mycompany.flowgear.net/customers/123/?auth-key=your-auth-key

Note that we do not recommend using this technique because it is possible that the URL will be logged.