Gatekeeper API

This article provides an overview of the API and describes the steps for accessing relevant documentation within Gatekeeper, as well as managing your API Keys.

Sections in this article:

• API Overview
• Gatekeeper API Documentation
• API Key Management
  • Add an API Key
  • Manage Existing API Keys
  • Revoke an API Key
• API Troubleshooting

API Overview

The API is available to Enterprise customers and uses the RESTful (Representational State Transfer) and JSON:API specification. JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

JSON:API is designed to minimise both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

Any custom data configured within Gatekeeper is also supported within the API. The API and related documentation are fully dynamic adapting to any changes in custom data that are implemented within the Configuration area. 

Gatekeeper API Documentation

The API documentation is specific to each Gatekeeper tenant and can be found by simply appending your tenant URL with "/api_docs" just after the four-digit tenant number (e.g. '1234' in the example below). Note that this number is different for each Gatekeeper customer instance. 

You will be presented with the below page which details your unique API Key and a full list of functions against each object with examples to get you started. 

Note that integration should only be attempted by appropriately trained technical resources. Any technical support required should be submitted via a ticket within the Gatekeeper support system.

API Key Management

API keys enable external applications to interact securely with your Gatekeeper tenant. Managing your API keys is essential for maintaining security, controlling access, and ensuring compliance with cybersecurity best practices. You can:

• Generate and manage multiple API keys.
• Assign permissions for individual API keys to control access to specific endpoints.
• Revoke or disable keys when necessary.

To manage API keys: 

1. From the navigation menu, expand Settings then click Configuration.
2. Click Integration.

The API Keys section displays a list of your existing API keys, including details of who generated the key and when.

Click the copy icon to copy the key to your clipboard.

Add an API Key

To create a new API Key:

1. Click + Add New Key.
2. Enter a name.
3. Ensure the Enabled toggle is switched on. 
4. Configure the permissions by selecting the appropriate checkboxes. This will determine whether read-only or write access is granted for each endpoint.
5. Once finished, click Save.

Manage Existing API Keys

You can update existing API keys if required. To do this: 

1. Click the pencil icon on the relevant row.
   
2. Update the name or amend the permissions by selecting/de-selecting the checkboxes.
   1. To disable a key temporarily, switch off the Enabled toggle. This is useful when you need to pause the integration, as the key can be re-enabled later.
3. Click Save to confirm your changes. 

Revoke an API Key

You can permanently remove an API key, ensuring it can never be used again. This is typically done when a key is compromised or no longer needed. To do this: 

1. Click the delete icon on the relevant row.
2. Type in the confirmation phrase and click Confirm.