API DocsCommunity
API Docs

Authentication

General

Azuqua’s API implements a signed and hashed header as its core authentication method. This method is used for every route inside of our API, with the important exception of running FLOs, which currently exist in V1. This includes FLO Invoke, Resume a FLO, Retry a FLO, and generating an Open API Spec. This allows you to set your own security setting for FLOs that are invoked via an external service- ranging from completely open, to the same secure, signed request that we require for all other routes.

To use the Azuqua API, you will need to generate a signature of the request that will be placed into a header. The Azuqua client will do this for you, but you may also generate it on your own.

Access Keys & Secrets

While using either the client or when generating the signed header by hand, you’ll need both your Access Key and Access Secret, which can be found inside the “User Settings” menu, under “Developer Settings”.

On this page, you'll see that you have an Access Key and Access Secret for each organization. This means that each resource is bound to a single organization, as opposed to a user.

Once you've grabbed the Access Key and Access Secret, if you are using the Azuqua client, you’ll be able to start making your signed, authenticated requests. If you are not using the Azuqua client, you’ll still need to generate your own signature using these values.

If you'd like to use the Azuqua client, check out "Azuqua Clients" for more information.

Generating the Signature, Step-By-Step

To generate the signed header on your own, you’ll need to follow a few steps:

  • Grab the correct URL path string, which starts just after the base path (https://api.azuqua.com/), including all query parameters and their values. For example: https://api.azuqua.com/org/<ID> becomes /org/<ID>
  • Create the base string, by joining the method name in lowercase, the URL path string from above, and the current ISO timestamp, with a colon (" : ") between each item. For example: Performing GET on the /org/<ID> route, at 9/13/17 at 3:55 PM PST becomes: get:/org/<ID>:2017-09-13T23:55:39.749Z
  • After this, append the stringified JSON representation of your body object, if you have one. If your body object is empty, make sure to append an empty string, not an empty object.
    • Example 1: GET on the /org/<ID> route (Get Organization), at 6/6/17 at 9:02 AM PST becomes get:/org/<ID>:2017-09-13T23:55:39.749Z, since there is no body object on a GET operation.
    • Example 2: PUT on the /org/<ID> (Update Organization), at 6/6/17 at 9:02 AM PST becomes put:/org/-ID-:2017-09-13T23:55:39.749Z{"name":"New Org Name","description":"New Org Description"}
  • Finally, sign this string by using an HMAC, SHA256 signature and your Access Secret, with a hex digest. There are many clients to complete this, even a function available while building FLOs inside of Azuqua.

Now that you’ve generated your signature, you can pass along the correct authentication headers. These will need to be added to every request. These are:

  • The x-api-hash header: This is the signature that we just generated above.
  • The x-api-accesskey header: This header will simply be the Access Key mentioned above.
  • The x-api-timestamp header: This is the current ISO timestamp. Azuqua uses this to confirm that the signature you created is from a recent request.
  • Note: Our API also depends on you specifying the "Content-Type" to be "application/json". Many clients implicitly include this, but in others you may need to specifically add this header in too. If you are using a FLO to perform this, you will need to specify this header.

If all of the above steps are completed properly, your request should be properly authenticated. If your authentication is incorrect, you may expect a 403 Unauthorized response.