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:

  1. Add a securityDefinitions object before the final closing brace of your OpenAPI Specification.
  2. Create an object inside the securityDefinitions object to define your basic authentication security.
  3. Inside the object:
    1. Add the property type with a value of apiKey.
    2. Add a property of name, with the name of the parameter that should hold the API key.
    3. Add a property of in, with a value of the location the API key parameter will be passed in.

      4. Note: Nintex Workflow supports passing the value in the query or the header.

  4. Inside the HTTP method of each operation that requires API authentication, add a security array.
  5. Inside the security array, add an object containing a property with:
    1. The key of the security definition object you created earlier.
    2. 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.
Copy 
{
  "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.+$"
        }
      }
    }
  }
}