OntoPop
Search…
⌃K

API Authentication

Authenticating API requests.
Last Updated: 01 March 2022 • Page Author: Jillur Quddus

API Keys

OntoPop provides native out-of-the-box support for authenticating applications accessing the OntoPop APIs via API Keys. To use OntoPop's native API Key-based API authentication mechanism, it must be explicitly enabled via the application context configuration, specifically in the security.authentication.api namespace.
OntoPop currently only supports the management of API Keys using the secrets engine configured in the security.secrets namespace (for example HashiCorp Vault, AWS Secrets Manager or Azure Key Vault).
Note that API Keys alone are not considered best-practice in terms of securing APIs given their propensity to appear in query string parameters and log files. If you are deploying OntoPop to a production environment, it is strongly recommended that you implement additional security measures to secure the OntoPop APIs, including but not limited to OAuth and JSON Web Tokens (JWT).

Schema

OntoPop manages API Keys using the following schema:
Property
Description
Example
key
The API Key itself that client applications must include in the X-API-Key request header.
ABCDEFGHIJKLMNOP12356789
issueDate
The date and time (UTC) that the API Key was issued, in yyyy-MM-dd'T'HH:mm:ss format.
2022-03-01T10:32:19
expirationDate
The date and time (UTC) that the API Key will expire, in yyyy-MM-dd'T'HH:mm:ss format.
2022-05-30T10:32:19
issuer
The name of the API Key issuer.
HyperLearning AI
client
The name of the client application.
Test App
enabled
Whether this API Key is enabled.
true
roles
A set of roles associated with this API Key for the purposes of authorization. Please see API Authorization for further details.
["ROLE_ONTOPOP_MANAGEMENT_API", "ROLE_ONTOPOP_TRIPLESTORE_API"]

Example API Key

Provided below is an example API Key that is issued to a client application:
{
"key": "ABCDEFGHIJKLMNOP12356789",
"issueDate": "2022-03-01T10:32:19",
"expirationDate": "2022-05-30T10:32:19",
"issuer": "HyperLearning AI",
"client": "Test App",
"enabled": true,
"roles": [
"ROLE_ONTOPOP_MANAGEMENT_API",
"ROLE_ONTOPOP_TRIPLESTORE_API",
"ROLE_ONTOPOP_SEARCH_API",
"ROLE_ONTOPOP_GRAPH_API",
"ROLE_ONTOPOP_MAPPING_API"
]
}

Request Headers

If OntoPop's native API Key-based API authentication is enabled, then client applications must include the API Key that they have been issued in the X-API-Key request header.

Authentication Flow

Assuming that an API Key has been included in the X-API-Key request header, OntoPop will perform the following ordered actions to authenticate the client application:
  1. 1.
    Check whether the provided API Key exists in the configured secrets engine. OntoPop will look for a secret that has the same name as the API Key key property prefixed with APIKEY_ for example APIKEY_ABCDEFGHIJKLMNOP12356789.
  2. 2.
    If it does not exist, then a HTTP 401 Unauthorized response status will be returned to the client application.
  3. 3.
    If it does exist, then check whether the API Key is enabled, and that its expiration date has not passed. If either of these checks fail, then a HTTP 401 Unauthorized response status will be returned to the client. If both of these checks pass, then OntoPop will examine the roles that are associated with the API Key to authorize the request. Please see API Authorization for further details.