Page tree
Skip to end of metadata
Go to start of metadata

There are two parts to controlling who can call your APIs:

  1. Configure which types of security to enable.
  2. Configure API Users

The default configuration allows anonymous callers.

Security types

  1. Navigate to the Profound.js IDE
  2. On the Home Ribbon, Click API Options and choose OpenAPI Configuration

This will open a new designer tab where configure several things, such as your API Explorer title bar information and API Security configuration.

To learn much more details into OpenAPI, see their documentation page for version 3.0.3.


There are 2 sections of this json file are what we are concerned with.

  • The "security" section.  This section is where you define what security schema are to be checked when an API is called.
    • These securities applied to all APIs.  A specific API route can override these securities.
    • Advanced: Notice that this section is an array of objects.  It does allow for configuring multiple schemas within each array element
    • See here for even more information.
{name}[]

Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object. The array MUST be empty.

To allow Anonymous callers, do not enter any name. i.e. { }


Field NameTypeApplies ToDescription
typestringAnyREQUIRED. The type of the security scheme. Valid values are "apiKey" or "http".
descriptionstringAnyA short description for security scheme. CommonMark syntax MAY be used for rich text representation.
namestringapiKeyREQUIRED. The name of the header, query or cookie parameter to be used.
instringapiKeyREQUIRED. The location of the API key. Valid values are "query", "header" or "cookie".
schemestringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.


This configuration is case-sensitive and must be a valid JSON document.


Below is a simple example of a single security using a single scheme.

  • The "name" of the security scheme can be anything, below the name this one "MyAPIKey".
  • Notice that "MyAPIKey" is defined as an "apiKey" type, and requires a property named "X-API-KEY" in the header.
  • Also, to enable this scheme authentication, it must be included in the "security" section and the name must exactly match.

With this configuration, this means when an API is called the caller must send a header with a property called "X-API-KEY".

The API Framework will attempt to authenticate to one and only one user with that "X-API-KEY" value.

 An example of a configuration that secures all APIs to require an API key credentials
{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "2.1.6"
  },
  "components": {
    "securitySchemes": {
      "MyAPIKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  },
  "security": [
    {
      "MyAPIKey": []
    }
  ]
}

Below is another simple example of a single security using a single scheme.

  • The "name" of the security scheme can be anything, below the name this one "User".
  • Notice that "User" is defined as a "http" type with scheme basic.  This means it requires the caller to send a encoded basic User/Password value for "Authorization" in the header.
  • Also, to enable this scheme authentication, it must be included in the "security" section and the name must exactly match.

With this configuration, this means when an API is called the caller must send a header with a property called "Authorization" that contain an standard encoding of basic user:password.

The API Framework will attempt authenticate to one and only one user with those matching credentials.

 An example of a configuration that secures all APIs to require User/Password credentials
{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "2.1.6"
  },
  "components": {
    "securitySchemes": {
      "User": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "User": []
    }
  ]
}


Below is an example that shows how you can use multiple schemes.

  • In the "security" section, there is still a single array element, however there it has two properties: "AppKey" and "ClientID"


With this configuration, this means when an API is called the caller must send a header with a property called "AppKey" and another property called "ClientID".

The API Framework will attempt to authenticate to one and only one user with both the "AppKey" and "ClientID" values.

 An example of a configuration that secures all APIs to require two API credentials
{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "2.1.6"
  },
  "components": {
    "securitySchemes": {
      "AppKey": {
        "type": "apiKey",
        "in": "header",
        "name": "AppKey"
      },
      "ClientID": {
        "type": "apiKey",
        "in": "header",
        "name": "ClientID"	
      }
    }
  },
  "security": [
    {
      "AppKey": [],
      "ClientID": []
    }
  ]
}


For advanced requirements

Below is an example of how you can combine different schema along with different securities. 

  • In the "security" section, there are now three array element.


With this configuration, this means when an API is called the caller must send one of the below combinations:

  1. For the "User" security:
    1. Header with property name "Authorization" with an basic encoded user:password
  2. For the "APIKey" and "AuthToken"
    1. Header with property name "X-API-KEY" and cookie with a name of AuthToken
  3. For the "AppKey" and "ClientID"
    1. Header with a property called "AppKey" and another property called "ClientID"

The API Framework will go through each of these array elements and attempt to authenticated to a one and only one user with those matching credentials.

A more advanced configuration
{
  "openapi": "3.0.3",
  "info": {
    "title": "My Company APIs",
    "version": "2.1.6"
  },
  "components": {
    "securitySchemes": {
      "APIKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      },
      "User": {
        "type": "http",
        "scheme": "basic"
      },
      "AppKey": {
        "type": "apiKey",
        "in": "header",
        "name": "AppKey"
      },
      "ClientID": {
        "type": "apiKey",
        "in": "header",
        "name": "ClientID"
      },
      "AuthToken": {
        "type": "apiKey",
        "in": "cookie",
        "name": "AuthToken"
      }
    }
  },
  "security": [
    {
      "User": []
    },
    {
      "APIKey": [],
      "AuthToken": []
    },
    {
      "AppKey": [],
      "ClientID": []
    }
  ]
}

API users

  1. Navigate to the Profound.js IDE
  2. On the Home Ribbon, Click API Options and choose User Authentication, then API Users


From here you can add, remove, and change credentials. 

** Based on configuration, an API User may require multiple identities for unique identification.


Below is the screen that is presented when adding or editing users.
** Notice under the Add button, there are additional options to add other types of identification.


  • No labels