Skip to content

Getting started

The GateKeeper API provides all the functionality that you need to integrate GateKeeper features to your web application, such as hosting panel and customer portal with REST-style JSON API. GateKeeper API is provided to BotGuard partners and subsequently, the APIs centre around partners' use of sub-accounts (Users). Subsequently, objects such as Servers, Devices and Websites must be assigned to a User object. Refer to Namespace structures, which demonstrates how objects are structured. Assigning Server and Device objects is optional and their inclusion depends on your use case.

Unlike the BotGuard Partner API, make all GateKeeper API calls through an endpoint hosted on your infrastructure. Replace localhost with the address of your API server in the examples below.

Authorization

The GateKeeper API uses API keys to authenticate requests. Each user account automatically generates a unique 32-character API Key, which is used to authenticate your API requests. This API key is intended for use inside the applications that are accessing the API. It is not intended for accessing the API through your browser.

When making a request, failure to provide an API key, or provision of a wrong or outdated key, results in an error. To find and use your unique account API key:

  1. Ensure that you are logged into your Botguard account.
  2. From the navigation bar, select Account. obtaining-api-key.png
  3. In the secondary menu, select Credentials.
  4. From the Your API Key section, copy your dedicated API key.
  5. You must send this copied API key in the Authorization header each time that you make requests. Like this: 
    Authorization: Bearer <api key>

Protect your API Key

Your key is the equivalent of a username and password that grants access to all of your website data. Treat it as carefully as any other password. BotGuard strongly recommends that you never use your API Key in your browser. It is intended only for use when accessing the API programmatically.

User interface

GateKeeper is an API-driven solution and provides all the necessary API methods to implement a custom user interface (UI) in your partner control panel, including rule editing and statistics. However, to speed up implementation of the UI, partners may opt to embed parts of the BotGuard UI as iFrames, using the following pages:

  • The page to configure website settings: https://apiv2.botguard.net/<lang>/website/<domain>/edit?api-key=
  • The page to view website statistics: https://apiv2.botguard.net/<lang>/website/<domain>/statistics?api-key=
  • The page to view website event log: https://apiv2.botguard.net/<lang>/website/<domain>/events?api-key=

For the above pages:

  • lang is the language supported, with the following options: en, es, fr, gr, pt, and ru.
  • domain is the domain name in which to display one of the above pages.
  • api key is the user's API key. For security reasons, it is important to use the user's BotGuard API key, rather than the primary account API key; i.e. your account.

Example

The following is an example of embedding the website settings page into a user interface:

<iframe
  src="https://apiv2.botguard.net/en/example.com/edit?api-key=xxx-xxx-xxx"
  width="1200"
  height="800"
  credentialless
></iframe>

Namespace structures

The following provides an example of how users, devices, servers, and websites are organized within an account:

namespace-structure.png