API key authentication
Use API key authentication to connect to an API using an API key.
Tip: If you need to add additional properties or validation to your connection, see x-ntx-connection-properties and x-ntx-connection-validation.
The following examples use API key authentication:
How to use API key authentication
To add API key authentication to your OpenAPI Specification:
- Add a securityDefinitions object before the final closing brace of your OpenAPI Specification.
- Create an object inside the securityDefinitions object to define your basic authentication security.
- Inside the object:
- Add the property type with a value of apiKey.
- Add a property of name, with the name of the parameter that should hold the API key.
- Add a property of in, with a value of the location the API key parameter will be passed in.
Note: Nintex Automation Cloud supports passing the value in the query or the header.
- Inside the HTTP method of each operation that requires API authentication, add a security array.
- Inside the security array, add an object containing a property with:
- The key of the security definition object you created earlier.
- An empty array as the property's value.
Where to use API key authentication
Use API key authentication in:
- The securityDefinitions object.
- The security array of each HTTP method that requires API key authentication.
{
"swagger": "2.0",
"host": "api.example.com",
"schemes": [ "https" ],
"produces": [ "application/json" ],
"consumes": [ "application/json" ],
"paths": {
"/example": {
"post": {
"summary": "Example operation",
"security": [
{
"myAPIAuth": []
}
],
"parameters": [...],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"securityDefinitions": {
"myAPIAuth": {
"type": "apiKey",
"name": "app_id",
"in": "query"
}
}
}
Limitations
OpenAPI Specification 2.0 does not support Bearer token authentication. When creating a connection using a Bearer token, the workflow designer must type Bearer into the field, followed by the token.
You can enforce this by adding x-ntx-connection-properties to the security definition, and using the pattern property to define a regular expression.
"securityDefinitions": {
"apikey_auth": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-ntx-connection-properties": {
"type": "object",
"required": [
"apiKey"
],
"properties": {
"apiKey": {
"type": "string",
"title": "API Key",
"description": "Prepend your API key with 'Bearer '. Example: Bearer dGVrSXg...",
"pattern": "^[Bb][eE][aA][rR][eE][rR]\\s.+$"
}
}
}
}
}