Authentication

While building a FLO, users can connect an account to a connector, set up their FLO, and then let it run. Azuqua handles all the hard work of authentication, and securely stores any pertinent authentication information (like credentials, API keys, or access keys obtained from an OAuth exchange) so it can be used whenever the FLO runs.

Azuqua supports 4 kinds of authentication: Basic, OAuth 1.0, OAuth 2.0, and Custom (often used for Key/Secret). In Custom authentication, you also may choose to define an authentication object that takes in custom parameters that you can then send over as part of your request to the API.

To set up authentication, go the Authentication section on the sidebar, and select the authentication type your API requires. Each form has slight variations, but all authentication types come in the basic form:

{
"type": ""
"authparams" : {
"<parameterName>": {
"type": "",
"displayname" : ""
}
}
}

Fields:

  • "type": The type of authentication (will be automatically populated)
  • "authparams": The set of parameters you would like to show up in the authentication visual elements of your Connector.
  • "<parameterName>": An individual authentication parameter that will be on your Connector. This name will not be surfaced onto the Connector itself, but will be the key you use to refer to the value throughout your methods. You may have as many of these as you need. Make sure to not include the "<" characters in your parameter name.
  • "type": The type of this parameter. Can be string, or password (hides the inputted value on the UI)
  • "displayName": The name that will be shown to the user on your Connector while they are building a FLO

Although Azuqua will handle the storage of authentication information, many APIs require you to use this authentication information to sign requests. To do this, all authentication parameters can be referred to in other methods using Mustache, in the form: "{{auth.parameterName}}".

Setting Up Basic Authentication

Use basic authentication when all you need to grant access to the API is a username and password, sent over in the headers or body of the request.

Template:

{
"type": "basic",
"authparams": {
"username": {
"type": "string",
"displayname": "Username"
},
"password": {
"type": "password",
"displayname": "Password"
}
}
}

Fields:

  • "type": must be set to 'basic' for basic authentication
  • "authparams": an object that contains the authentication parameters users will enter. For Basic auth, these are usually "username" and "password"
  • "type": can be 'string' or 'password.' If type is 'password,' the input will be hidden as the user types it in
  • "displayname": the name that will display above the authentication parameter in the UI

Example:

{
"type": "basic",
"authparams": {
"username": {
"type": "string",
"displayname": "Username"
},
"password": {
"type": "password",
"displayname": "Password"
},
"instance_url": {
"type": "string",
"displayname": "Instance URL (w/o https)"
}
}
}

Later on, you can reference these parameters using the Mustache templates {{auth.username}} and {{auth.password}}.

Setting Up OAuth 1.0

Template:

{
"type": "oauth",
"version": "1.0",
"request_url": "",
"access_url": "",
"consumer_key": "",
"consumer_secret": "",
"callback": "{server}/app/oauth/(YOUR APP)/authorize",
"signature_method": "HMAC-SHA1",
"nonce_size": null,
"redirect": ""
}

 

Fields:

  • "type": must be set to 'oauth'
  •  "version": must be set to 1.0 for OAuth 1
  • "request_url": the external URL where the token request will be made
  • "access_url": the external URL where the request token will be exchanged for the access token
  • "consumer_key": the access key obtained from the application
  • "consumer_secret": the access secret obtained from the application
  • "callback": the callback URL. Substitute the Connector's unique filename (the one you created when you first saved your Connector) for "(YOUR APP)"
  • "signature_method": must be 'HMAC-SHA1'
  • "nonce_size": must be null
  • "redirect": the redirect URL (may also be called the authorize URL).

Optional Fields:

  • "authparams": an object that contains the authentication parameters users will enter. Only include authparams in the OAuth object if you require users to enter additional data before you can run the OAuth exchange, such as an instance URL. Each parameter defined in this object can be referenced as {{auth.(parameter key)}} using Mustache.
  • "type": can be 'string' or 'password.' If type is 'password,' the input will be hidden as the user types it in
  • "displayname": the name that will display above the authentication parameter in the UI

The access token that results from the OAuth exchange can be referenced from inside each method and hashed into HTTP calls using the Mustache template {{auth.access_token}}. After you have set up your authentication, all requests to the API will be automatically signed for you according to OAuth 1.0 protocol.

OAuth 2.0 Redirect URL
Some applications require you to set acceptable callback or redirect URLs when you register your application. You must add this redirect URL to your application to be able to run OAuth 1.0 from the Connector Builder, Beta Environment, and Production Environment:

https://api.azuqua.com:443/app/oauth/(FILENAME)/callback

Substitute the Connector's unique filename (the one you created when you first saved your Connector) for "FILENAME".

Setting Up OAuth 2.0

For information about OAuth 2.0 types, please check out this article. We currently allow integration with one part, two part and refresh-able OAuth 2.0 exchanges. We default our template for Authorization Code grants (a two part OAuth exchange, with a refresh option).

Template:

{
  "type": "oauth",
  "version": "2.0",
  "base_site": "",
  "authorize_path": "",
  "access_token_path": "",
  "access_token_name": "access_token",
  "refresh_token_name": "refresh_token",
  "client_id": "",
  "client_secret": "",
  "appParams": {
    "one": {
      "response_type" : "code"
      "state": true,
      "redirect_uri": "{server}/app/oauth/(YOUR APP)/authorize"
    },
   "two": {
     "grant_type" : "authorization_code"
     "redirect_uri": "{server}/app/oauth/(YOUR APP)/authorize"
    },
    "refresh": {
      "grant_type" : "refresh_token"
    }
  }
}

Fields:

  • "type": must be set to 'oauth' for OAuth 2
  • "version": must be set to 2.0 for OAuth 2
  • "base_site": the base URL (may be omitted if the authorize_path and access_token path do not come from the same base site)
  • "authorize_path": the URL (in addition to base_site) where users will be directed to give authorization
  •  "access_token_path": the URL (in addition to base_site) where the access token will be obtained
  • "access_token_name": the key of the access token in the response
  • "refresh_token_name": the key of the refresh token in the response
  • "client_id": the client ID obtained from the application. Automatically appended to all steps of your authentication.
  • "client_secret": the client secret obtained from the application. Automatically appended to all steps of your authentication.
  • "appParams": an object representing the parameters you'll be sending in each step of your OAuth exchange.
    • "one": an object that contains the query parameters required for the first exchange of your authentication process. The parameters included in the template are common parameters, but not all applications use the same fields.
      • "state": a boolean that if true will include an unguessable state value in the OAuth exchange
      • "redirect_uri": the URL where users will be sent after authorization. Substitute the Connector's unique filename (the one you created when you first saved your Connector) for "FILENAME", but leave "{server}"- as our engine will make that swap for you at runtime.
      • "response_type": This parameter is specific to Authorization Code Grant OAuth 2.0
    • "two": an object that contains the parameters required for the second step of your authentication except for "code", which is automatically passed to the second leg of the authentication exchange. The parameters included in the template are common parameters, but not all applications use the same fields.
      • "redirect_uri": the URL where users will be sent after authorization. Substitute the Connector's unique filename (the one you created when you first saved your Connector) for "FILENAME"
      • "grant_type" : This parameter is specific to Authorization Code Grant type of OAuth 2.0
    •  "refresh" (optional), an object that contains the parameters required to exchange a refresh token for a new auth_token if the token expires

Optional Fields:

  •  "authparams": an object that contains the authentication parameters users will enter. Only include authparams in the OAuth object if you require users to enter additional data before you can run the OAuth exchange, such as an instance URL. Each parameter defined in this object can be referenced as {{auth.parameterName}} using Mustache throughout the rest of your connector JSON.
  •  "type": can be 'string', 'password', or 'option'. If type is 'password,' the input will be hidden as the user types it in. If the type is 'option', you will need to provide an array of objects called "choices", where each item contains an "optionValue" and "displayName" field, for more information on 'option' types see Parameters.
  • "displayname": the name that will display above the authentication parameter in the UI

The access token and refresh token that results from the OAuth exchange can be referenced from inside each method and hashed into HTTP calls using the Mustache reference {{auth.access_token}} or {{auth.refresh_token}}.

OAuth 2.0 Redirect URL
Some applications require you to set acceptable callback or redirect URLs when you register your application. You must add these redirect URLs to your application to be able to run OAuth 2.0 from the connector builder and from the production environment:

https://api.azuqua.com:443/app/oauth/(FILENAME)/authorize

Substitute the Connector's unique filename (the one you created when you first saved your Connector) for "FILENAME". Note, if you are developing in Azuqua's Beta environment, make sure that you use "betaapi" instead of "api" in the above URL.

Setting Up Custom Authentication

Custom authentication allows you to define your own authentication parameters. Often, custom auth is used for key/secret authentication.

Template:

{
"type": "custom",
"authparams": {
"parameterName": {
"type": "string",
"displayname": ""
}
}
}

Fields:

  • "type": must be set to "custom" for custom authentication
  •  "authparams": an object that contains the authentication parameters users will enter. For custom auth, you can define any authparams as you like
  • "parameterName" : Replace this with the name of the parameter you'd like to add.
    • "type": can be 'string' or 'password.' If type is 'password,' the input will be hidden as the user types it in
    • "displayname": the name that will display above the authentication parameter in the UI

Example:

{
"type": "custom",
"authparams": {
"apikey": {
"type": "string",
"displayname": "Username"
},
"secret": {
"type": "password",
"displayname": "Password"
}
}
}

No matter how you define your authentication schema, you'll be able to reference your authentication parameters later on using Mustache in the form: "{{auth.parameterName}}"