Documentation
    {{docApp.userSession.userId}}
    {{docApp.userSession.userName}}
    {{docApp.userSession.email}}
    Issuer : {{docApp.userSession.issuerInstance}}
    Expires : {{new Date(docApp.userSession.validUntil).toLocaleDateString()}}

{{docApp.title}}

{{docApp.description}}

How can we help?

{{docApp.searchError}}
{{product.name}}

Searching in {{docApp.searchFilterBySpecificBookTitle}}

{{docApp.searchResultFilteredItems.length}} results for: {{docApp.currentResultsSearchText}} in {{docApp.searchFilterBySpecificBookTitle}}
Search results have been limited. There are a total of {{docApp.searchResponse.totalResultsAvailable}} matches.

You have an odd number of " characters in your search terms - each one needs closing with a matching " character!

{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}

{{docApp.libraryHomeViewProduct.description}}

  1. {{book.title}}

{{group.title || group.id}}

{{group.description}}

  1. {{book.title}}

{{group.title}}

{{book.title}}
More...

API Keys

The Hornbill Platform supports the use of API Keys which are used primarily for non-interactive machine-to-machine integrations with other systems. For normal interactive sessions, various authentication methods are supported, but the basic idea is, the user is prompted for some credentials, and there are a number of exchanges between the user/browser and the service to establish a secure connection. When using API’s, this authentication process is too complex and undesirable for automated systems, primarily because no human actor can be involved, and for this reason. the Hornbill platform supports API keys.

An API key, also known as an Application Programming Interface key, is a unique identifier that allows another application or system to access and use the Hornbill API’s without the need for interactive authentication exchanges. An API key acts as a security token that authorizes access to specific API resources and functions of the Hornbill Platform and it applications.

API keys are generated by the Hornbill platform and are always associated with a specific user account. The user account provides the security controls foundation which the API key inherits. When making API requests, the key is included in the request as either parameter in the request payload, or in the Authorization request header as a bearer token. The Hornbill service then verifies the key to ensure that the requester has the necessary permissions to access the requested API resources and establishes a new, or binds to an existing session.

From a security perspective, API keys are far more vulnerable to abuse because the process of interaction between the Hornbill service and the person logging in is removed. In effect, an API key is a trusted authorization token that simply lets you in the door - without any further interactive challenge.

For this reason, when using API keys in Hornbill, you are able to define additional restrictions on an API key its self, to further limit what the API key can be used for. These restrictions are known as API Key Rules and can be defined to control both IP Address source(s) and/or limit the API key to only work with specific set of API’s

API keys can vary in complexity and format, but they are often alphanumeric strings. While they are designed not to be human “rememberable” it’s important to keep API keys confidential and use secure transmission methods to protect them from unauthorized access and use.

For information on best practice guidance on using API keys within Hornbill, please see Best Practice Use of API Keys in Hornbill

API Key Security Controls

If you create an API Key on a specific user account, by default the user of the API Key will have all of the same rights and privileges ast the user account the key is associated with, and this will generally mean the user of the API key will have access to a large number of API’s. For most use cases, API Key uses, such as integrations generally only need to use a small handful of API’s, and you often want to make sure that your API key is being used from a known single, or set of source IP addresses. To provide this more granular control you can use API Key Rules.

There are two types of API Key rules you can use in Hornbill

  • IP Address: If you do not specify any IP Address rules, then requests from any IP address will be accepted. However, if you want to limit which IP Addresses can use the API Key, then you can specify one or more allowed IP Addresses. IP Address rules can be specified as single ipv4 addresses, or as allowed network address ranges using the Classless Inter-Domain Routing (CIDR) network address formatting convention.

  • API Filter Rules: You can limit an API Key from accessing most API’s and limit to just the API’s the integration or use case where the API Key is being used. If you do not specify API Rules, then the API Key user can invoke any API that the user account associated with the API key has permissions to.

  • WebDAV Filter Rules: You can limit an API Key from accessing any WebDAV resource to restrict both the operation (GET, PUT, PORPFIND, DELETE etc…) and a resource path, including a right match wildcard option. If you do not specify WebDAV Filter Rules, then the API Key user can access/use all resources accessible to the account session related to the API key without restriction.

Here are some examples of both IP Address and API Rules and how to define them.

Rule Description
ip=142.250.200.46 Will allow API calls using this API key from the specified address
ip=142.250.200.0/24 Will allow API calls using this API key from the specified network address 142.250.200.x where we are using the CIDR representation of the network mask, in this example /24
dav=GET session/* Will allow the caller to do GET operation on any file in the session folder
dav=PUT session/* Will allow the caller to do a PUT operation and upload a file into the session folder
dav=* session/* Will allow the caller to perform any supported WebDAV operation
session:* Allows any API in the session service
session:getSessionInfo Will allow this API. You can specify multiple individual API calls when more than one API call should be allowed
session:get* Allow any API with a name that starts with ‘get’ within the session service
apps/com.hornbill.core/* Allows all com.hornbill.core API’s
apps/com.hornbill.core:addHistory Allow the Core application defined global API addHistory
apps/com.hornbill.core/Achievement:addAchievement Allows the application defined for entity Achievement
apps/com.hornbill.core/Achievement:* Allows the application defined for entity Achievement’s API’s
  • Version {{docApp.book.version}}
  • Node {{docApp.node}} / {{docApp.build}}
In This Document