Add API key authentication
|
In this example, you will create an Xtension |
API key authentication requires Nintex Automation Cloud to provide a secret security token when making the request An attempt to use a feature or operation of a third-party API. of the API A programming interface that defines how software can be interacted with by other software., which must be accepted by the API for the API to process the request. The token can be provided either in the request header The section of the HTTP request that defines the operation of the request, including authorization., or in the query Part of the URL that does not fit into the path structure, and provides additional information or parameters for the request. The query is prefaced by a question mark (?) in the URL, for example: http://example.com?color=blue..
When using Xtensions with API key authentication, you must create a connection The stored authorization credentials for a connector. that stores the security token so it can be passed to the API with the requests.
The complete OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. and icon for this example are available here.
Tip: Want the short version? Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.
Looking for other examples?
The following examples also use API key authentication:
Or see the how-to guide on API key authentication.
API key authentication
To add API key authentication to an OpenAPI Specification, you:
- Sign up for an API key with the service you want to use
- Define the API key authentication object inside the securityDefinitions object
- Reference this API key authentication object inside the HTTP method objects that require authentication
Tip: You can request additional connection information, such as a database name, using x-ntx-connection-properties, and validate your connection when it is created using x-ntx-connection-validation.
Acquire a security token for the API
The API uses a security token to identify who is making the operation call. You will provide Nintex Automation Cloud with this token when you create a connection to this Xtension. To acquire your security token for this example:
- Sign up to OpenExchangeRates.org for the Forever Free plan at this link.
- Follow the instructions on the Open Exchange Rates page to get your API key.
- Record the Name and the App ID somewhere safe: it identifies you to the OpenExchangeRate.org API, and should be kept secret.
Define API key authentication
Step 1: Create the basic OpenAPI Specification
Create an OpenAPI Specification that:
- uses the host The domain name of the third-party API's URL.openexchangerates.org.
- accepts HTTPS and produces application/json.
- has a get operation A single request to a third-party API. Operations often become actions in the workflow designer. to /latest.json that passes the base currency to provide exchange rates for in the query Part of the URL that does not fit into the path structure, and provides additional information or parameters for the request. The query is prefaced by a question mark (?) in the URL, for example: http://example.com?color=blue..
- responds The return from a third-party API after a request has been made by the client.200 with a schema that returns the base selected currency and the rate to
the currencies in USD, GBP, EUR and AUS.
In this instance, the API actually provides more currencies than these four. To keep the Workflow designer manageable, we are limiting our definition to just the currencies we want to use.
Note: To ensure users only submit valid currency codes to the API, use an enum to pass the base currency parameter A piece of information passed to a third-party API during a request..
Restricting parameter options with enums
Many APIs only accept specific values in parameters, such as airport codes or currency codes. To avoid sending the API a parameter it can't understand, you can pre-define the accepted parameters using an enum. An enum (short for enumeration) is a special data type that lists an array of accepted values.
"enum": [
"USD",
"GBP",
"EUR",
"AUD"
]
When configuring the custom action
A task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. in
Nintex Automation Cloud, an enum parameters is displayed as a
drop-down list.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Currency Rates"
},
"host": "openexchangerates.org",
"basePath": "/api",
"schemes": [
"https"
],
"produces": [
"application/json"
],
"paths": {
"/latest.json": {
"get": {
"summary": "Get exchange rates",
"description": "Get exchange rates",
"operationId": "testBasicAuth",
"produces": [
"application/json"
],
"parameters": [
{
"name": "base",
"in": "query",
"required": false,
"type": "string",
"enum": [
"USD",
"GBP",
"EUR",
"AUD"
]
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/rateResult"
}
}
}
}
}
},
"definitions": {
"rateResult": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"rates": {
"type": "object",
"properties": {
"USD": {
"type": "number"
},
"GBP": {
"type": "number"
},
"EUR": {
"type": "number"
},
"AUD": {
"type": "number"
}
}
}
}
}
}
}
Step 2: Create the security definitions object.
Create the securityDefinitions object at the end of the OpenAPI Specification, after the definitions object but before the final closing brace. Make sure you add a comma to the end of the definitions object.
"definitions": {
"rateResult": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"rates": {
"type": "object",
"properties": {
"USD": {
"type": "number"
},
"GBP": {
"type": "number"
},
"EUR": {
"type": "number"
},
"AUD": {
"type": "number"
}
}
}
}
}
},
"securityDefinitions": {
}
Step 3: Create the API key authentication definition
Inside the securityDefinitions object, create an object to define the API key authentication. You can name the security object any name that is unique within the OpenAPI Specification. In this example, we have named it myApiKey.
Add a type with a value of apiKey to the object to define it as API key authentication.
"securityDefinitions": {
"myApiKey": {
"type": "apiKey"
}
}
Step 4: Add the API authentication parameter details
Inside the myApiKey object, add a name key for the parameter to hold the security token. The value must be the parameter A piece of information passed to a third-party API during a request. name defined by the API.
Add the location it will be passed in with the in key.
"securityDefinitions": {
"myApiKey": {
"type": "apiKey",
"name": "app_id",
"in": "query"
}
}
Step 5: Add a security array to the HTTP method object
Inside the HTTP method object, create a security array.
"paths": {
"/latest.json": {
"get": {
"summary": "Get exchange rates",
"description": "Get exchange rates",
"operationId": "testBasicAuth",
"produces": [
"application/json"
],
"security": [
]
}
}
}
Step 6: Add the security object reference to the array
Inside the array, reference the security object you defined earlier by using its name as the key, and opening and closing brackets as the value.
"paths": {
"/latest.json": {
"get": {
"summary": "Get exchange rates",
"description": "Get exchange rates",
"operationId": "testBasicAuth",
"produces": [
"application/json"
],
"security": [
{
"myApiKey": []
}
]
}
}
}
The OpenAPI Specification
This is the complete OpenAPI Specification that uses API key authentication to retrieve exchange rates.
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Currency Rates"
},
"host": "openexchangerates.org",
"basePath": "/api",
"schemes": [
"https"
],
"produces": [
"application/json"
],
"paths": {
"/latest.json": {
"get": {
"summary": "Get exchange rates",
"description": "Get exchange rates",
"operationId": "testBasicAuth",
"produces": [
"application/json"
],
"security": [
{
"myApiKey": []
}
],
"parameters": [
{
"name": "base",
"in": "query",
"required": false,
"type": "string",
"enum": [
"USD",
"GBP",
"EUR",
"AUD"
]
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/rateResult"
}
}
}
}
}
},
"definitions": {
"rateResult": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"rates": {
"type": "object",
"properties": {
"USD": {
"type": "number"
},
"GBP": {
"type": "number"
},
"EUR": {
"type": "number"
},
"AUD": {
"type": "number"
}
}
}
}
}
},
"securityDefinitions": {
"myApiKey": {
"type": "apiKey",
"name": "app_id",
"in": "query"
}
}
}
Create the workflow
Step 1: Add your Xtension
Import the OpenAPI Specification you created into Nintex Automation Cloud:
- Open your Nintex Automation Cloud tenancy.
- Click Xtensions in the dashboard to open the Xtensions page.
- Click
in the Private connector list. - Click Choose a file. Navigate to the OpenAPI Specification on your computer.
- Wait for Nintex Automation Cloud to validate the file.
- Click Next.
- Nintex Automation Cloud detects the API key security template.
- Click Next.
- Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
- Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
- Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
- Click Publish.
Step 2: Create the workflow
The workflow will retrieve the currency conversion rates based on the United States dollar and compare the AUD rate against a threshold level to recommend whether purchases in Australian dollars be approved.
For more information on creating workflows, see the Workflow Designer.
To create the workflow:
- Click Create workflow in your Nintex Automation Cloud tenancy.
- Configure the Start event to be a Nintex form with two variables:
- Email (text)
- Purchase request (text)
- Purchase amount in AUD (decimal)
- Drag the Get exchange rates action from the action toolbox to after the Start event.
- Click the Connection field and select Add new connection.
- Type the Name you recorded from OpenExchangeRates.org in the Connection name field.
- Type the App ID you recorded from OpenExchangeRates.org in the Api key field.
- Select USD in the Base configuration
field.
- Create a decimal variable to store the Results Rates AUD return value.
- Drag a Calculate a value action below the Get exchange rates action.
For more information, see Calculate a value. - Configure the Calculate a value action to:
- Divide the purchase amount by the Result Rate variable.
- Store the result in a new US Purchase Price variable.
- Drag an Assign a task action below the Calculate a value action.
For more information, see Assign a task. - Configure the Assign a task to send an Express Approval request to the financial officer with the US purchase price and item details.
For testing purposes, use your own email as the recipient. - Drag a Send an email action into each branch.
For more information, see Send an email. - Configure the Send an email actions to email the purchase requester that their request has been rejected or approved.
- Click Test to test the workflow.
- Save or publish the workflow.
For more information on designing forms in Nintex Automation Cloud, see Design a form.
Tip: If you want to troubleshoot an Xtension, select Development as the Assigned Use when you publish the workflow. Development workflows display more detailed error messages in their instance details. Republish your workflow as Production when you're ready to use it.