Overview
Welcome to the Azuqua API 2.0!
Getting Started
This hub is meant to document all the functionality of the newest version of our API, and to serve as a starting point for developers looking to leverage Azuqua's automation programmatically.
This version of our API will also see additions in the next coming months, so be sure to check under "Announcements" on our landing page to see what's new!
Some points of interest for people getting started are the Authentication section, and information about our various clients here.
In this documentation, you'll find that each route has a couple of things:
- A description of what the route does
- Sample responses and errors
- Generated ways to make the given request in cURL, Node, Ruby, Javascript, and Python (note, you will need to make the authorization headers on your own from these generated code snippets)
- A list of parameters that can be passed in a specific request
Accessing Version 1.0
If you are looking for a route from version 1.0 of our API and don't see it, be sure to check out v1.0 documentation on this site. You can access it by clicking on the v2.0 in the upper left toolbar on this page, and selecting v1.0.
Some routes that you'll find there that will soon make it over to v2.0 are: Invoke a FLO, Resume a FLO, Retry a FLO, Generating a Open API 2.0 Spec for a FLO, Rules Engine routes, Telemetry routes.
Authentication
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.
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.
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 becomesget:/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 becomesput:/org/-ID-:2017-09-13T23:55:39.749Z{"name":"New Org Name","description":"New Org Description"}
- Example 1: GET on the
- 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.
Azuqua Clients
Due to Azuqua's signed security headers, you may find it significantly easier to utilize our API via our variety of clients.
We provide full clients for our API v2 in the following languages (links will take you to the github repo for each, at the appropriate branch):
We are currently operating on the apiv2
branch of each client library.
In each repo's README, you'll find information about the setup for each library and the basics of how to use them.
If you are trying to use v1.0 routes, be sure to check out the v1.0 of this page, as it will have the clients needed to perform that functionality listed there.
Rate Limiting
Rate-limiting inside of Azuqua is based on two things:
- Access Key & Access Secret
- Resource type. This includes items like, "FLOs", "Folders", "Accounts", "Organization", and more.
The current rate limit is set at 10 requests per second per resource for each Access Key/Secret pair.
Read All Accounts
Return information about all accounts you have access to in this organization.
Copy FLO
Copy a FLO into a provided folder. If the folder is not provided, this route will copy the FLO into the same folder as the original FLO.
Copy FLO into Organization
Copy a FLO into a provided organization, while optionally copying it into a specified folder.
Update User Permissions to Folder
Update the permissions a user has a on a given folder.
Update User Role in Organization
Update a user's role (billing admin, admin, member) inside your organization. Note, you may not update someone away from being billing admin.