INDEX

Documentation Library

Search for information on Hornbill Documentation.

Filter

Books

All
{{book.title}}
{{book.foundCount}}

Products

{{product.name}} {{docApp.searchFilteredProducts[product.id].returnedCount}}

{{docApp.searchResultFilteredItems.length}} results for "{{docApp.currentResultsSearchText}}" in {{docApp.searchFilterBySpecificBookTitle}}

{{resultItem.title}}

{{resultItem.url}}

Have questions about this site?

What is this site?

This website is Hornbill's new product documentation website and is currently under development.
It is intended that all existing and future public-facing documentation we produce will be available to search, browse and share.
Hornbill's current documentation is available at Hornbill Wiki but over time this content will be migrated to this documentation site.
Please feel free to have a look around at any time.

Why has Hornbill created this site?

Hornbill's products have moved on considerably since we introduced it almost 10 years ago. At the time, the MediaWiki tool was sufficient, but we have outgrown it.
Our customers are more enterprise focused and more self-sufficient than ever before, so for 2023 and beyond we have established a new documentation platform and team to drive our documentation initiative forwards.
We are aiming to deprecate the use of Hornbill Wiki for most Hornbill related documentation.
We want to enable our growing partner network with product resources and information, documentation beyond our Wiki approach is required.
We could definitely do with some help, and may even pay for some! If you have domain knowledge and would like to help, please check out our Hornbill Docs Contributor Guide and contact the Hornbill docs team at docs@hornbill.com.

What will this site be good for?

Community contribution will be facilitated, encouraged, and most welcome.
High quality documentation, will be kept up to date as rapidly as our products evolve.
Real-time content search and discovery.
Articles organized into books, books into libraries, creating a more natural and logical structure to our documentation.
Legacy API documentation and various other documentation sources will all be consolidated into a single unified documentation system.
Documentation available in browser as well as printable/viewable as PDF on demand.
Personalized documentation experience, allowing dark/light mode, article subscriptions, social media sharing and other useful features.
Almost all publicly available documentation on docs.hornbill.com will be open-source and available to fork on GitHub, allowing customers to derive their own custom documentation around Hornbill products should they wish to.

What is the timeline for this site?

We have taken the decision to publish and make available early, there is very little content at this time.
As and when we have completed/usable documentation, it will be published here.
We have a host of additional features we wish to add over time, so please watch this space.
We expect most of our existing documentation should be reviewed/migrated to docs.hornbill.com over the coming months.
The documentation project will be ongoing, will continue to expand, evolve and improve day-by-day.

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

{{book.title}}

{{book.title}}

More...

API Keys Security Considerations

When using API keys, security is an important consideration which should not be overlooked. Its important that you keep your API keys secure, API keys in many respects should be treated like pass codes. Exposing API keys to an extended audience can result in the associated user account being compromised, which could lead to many security issues including unauthorized access and data theft/loss. To keep your API keys secure, follow these best practices:

Do not embed API keys directly in code: API keys that are embedded in code can be accidentally exposed to the public, for example, if you forget to remove the keys from the code that you share. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application’s source tree.
Do not store API keys in files inside your application’s source tree: If you store API keys in files, keep the files outside your application’s source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.
Do not show your API keys in videos, documents, or other shareable content:. If you do need to show screens where your API key appears, use your graphics tools to redact the specific key identifiers.
Restrict your API keys to be used by only the IP addresses that need them: By restricting the IP addresses that can use each key, you can significantly reduce the likelihood of API key misuse. You should specify the hosts and/or network ranges that are valid for each.
Restrict your API keys to be used only for specific APIs: If the use case for your API requires a number of APIs, restrict the API key to only be able to invoke only those specific APIs.
Delete unused API keys: To minimize your exposure to attack, delete any API keys that you no longer need.
Rotate your API keys periodically: The longer an API key is in use, the more known it may become. It’s always a good idea to rotate your API keys periodically by creating a new key beside the existing one, updating the integration/use of the key, and then deleting the old key.
Set Expiry Dates on API Keys: Force key rotation by setting hard dates on the validity of the API key.

Recommended Best Practice: Using Hornbill Platform API Keys

The following guidance sets out Hornbill’s recommendations for best practice when using API Keys to integrate with or profile tools or other systems with machine-to-machine access to your Hornbill instance. The Hornbill platform is a very flexible system with a lot of possible configuration options, there are always exceptional edge-cases, but as a general rule we strongly recommend that you follow these guidelines as closely as possible to ensure you deploy secure and reliable machine-to-machine integrations, import tools and custom automation’s.

1. Use one account for each API Key function you deploy

The Hornbill platform allows you to create multiple API keys associated with a single user account. It is tempting to create one account and then create all of your API’s on that account, or, create API keys for integrations and/or automation’s under one of your normal user accounts, or even, just create your API keys on the ‘admin’ account. While this works, Hornbill does not recommend this practice for these reasons:

The account you create would need a superset of all rights needed by all API keys/use cases (automatic in the case of the ‘admin’ account)
You would lose the ability to maintain a traceable audit trail of activity carried out in the context of a specific API key because on the Hornbill platform, audits and trace logging is tied into the user account objects.
Following the best-practice principle of minimal required rights/privileges is impossible to achieve when you are effectively sharing one account amongst multiple API key use cases/projects.

Sometimes there is a valid reason for having more than one API key on an account, especially when you have, for example multiple, related data imports. You may want each one on a separate API key, but they are a group of import scripts/functions running as “the nightly import”. However, it should be noted that the primary purpose of allowing more than one API key per account is to facilitate seamless API key cycling and testing, etc.

2. Always apply IP Address restriction rules.

Almost every use case for an API key is for some form of integration, data import or automation and as a general rule you would know exactly where these processes/tools are running. By limiting the use of the API key to a specific IP address (or group of IP addresses) you will be limited in the ability for the API key to be abused, even if the key its self has been compromised.

Note

IP Address restriction rules are only available for platform build 3755 and above

3. Always create API Filter Rules to limit APIs that can be Invoked

Most integrations or tools that will make use of API keys will typically only need to invoke a very small handful of API methods on the Hornbill platform. You should always create specific API Filter rules on each API key, limiting the ability for the API Key use case to invoke API methods you were not expecting.

4. Never use the ‘admin’ account or any user account that has super-user right granted for API Keys

While its tempting to create API’s on all-powerful user accounts, this is not recommended and should be avoided. The default ‘admin’ account on your Hornbill instances is a very powerful account, the privilege level applied to these super-user accounts bypass a lot of security checks and other security controls. While its technically possible to create one or more API keys on the ‘admin’ account, or other super-user designated account, even with the IP Address Rules and API Filter Rules in place, its simply not a good idea to make a non-interactive super-user account so easily accessible with a simple key.

5. Rotate your API keys.

You should consider rotating your API keys periodically. Hornbill provides an option to have an API key expire on a future date you specify, and we recommend that you never keep API Keys valid for longer that 2 years. Its a good idea to set yourself a periodic reminder to achieve this. This is especially true as individuals move in and out of your organization, make sure you cycle any API keys that person may have had site of, or cause to work with.

6. Set API Key Expiry Times

It is good practice when creating an API key, you should always set a reasonable expiry date on keys to ensure if forgotten about they become invalid. It is not uncommon for API Keys to fall out of use, and by setting an expiry time, you can ensure those keys will automatically become invalid.

In This Document

{{docApp.title}}

{{docApp.description}}