Client Certificates are the recommended mechanism for authorizing invokes of Workflows via REST API.

When you invoke a Flowgear Workflow, you provide the client certificate for the HTTPS connection and Flowgear validates the public key of the certificate.

Managing Client Certificates

Access the API Keys Management Pane by clicking on your Site name in the left-hand menu and then choosing API Keys.


Click + to generate a new API Key, then choose New Certificate-based Key

Name

Provides a unique name for the key. When a invoked using a key, the InitialisationXml Property will indicate the key that was used in the form 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

Optionally select a specific Site Environment to cause Workflows invoked using this Certificate to launch under the chosen Site Environment. This is recommended practice as it enables separate certificates to be used for different environments.

Important: If you have selected a non-Production environment under this setting, you must also include the desired environment in the querystring of your calls. For example, &_profile=Test.

Certificate

Upload the public key of the certificate (.cer file) you would like to use to authorize API calls.

Once uploaded, the thumbprint of the certificate will be shown.

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. Flowgear will only authorize the Key against the selected Workflows.

Generating a Self-Signed Client Certificate

We recommend that you only using self-signed certificates for testing purposes. The simplest way to do this is via OpenSSL.

To generate the certificate:

openssl.exe req -x509 -newkey rsa:4096 -sha256 -keyout selfsigned.key -out selfsigned.crt -subj "/CN=selfgisned.com" -days 600

(Upload the .crt file here in to Flowgear).

If you want to install the certificate into the Windows Certificate Store, convert the private and public keys into a .pfx file using the following:

openssl.exe pkcs12 -export -name "selfsignedcert" -out selfsigned.pfx -inkey selfsigned.key -in selfsigned.crt

Providing a Client-side Certificate in an API call

When invoking the Flowgear API, you must provide the client-side certificate that is associated with the appropriate API Key.

On Windows, we recommend that you install the certificate into the certificate store and then access the certificate by its thumbprint. This certificate must then be referenced in the client-side code so that it is used to establish the TLS session.

See the C# example of how to use a client-side certificate


Did this answer your question?