> For the complete documentation index, see [llms.txt](https://help.security.gallagher.com/knowledge-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item.md).

# Creating a REST API Client Item

### Introduction

The REST Client item represents a credential that clients (other computers) can use to connect to the REST API Client. The properties hold a secure token which is used to authenticate the client.

**Note:** Operators require the "Advanced User" privilege to save a REST Client item.

### Before you begin

Before you begin this procedure, ensure the Client Certificate is created on the host machine that will be running the REST client. Refer to [Creating the Client Certificate](https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item/creating-the-client-certificate.md) for instructions.

Using a client certificate increases security by limiting incoming REST connections to the Command Centre Server. REST connections will only be able to come from machines with a client certificate whose thumbprint matches the Server's Client Certificate Thumbprint.

### Procedure

1. Click **Configure** from the menu bar, then **Services & Workstations**.

   The **Services and Workstations** List Window opens (in [grid view](https://help.security.gallagher.com/knowledge-hub/configuration-client/introduction-to-command-centre/knowing-your-way-around/list-windows/grid-view.md)).
2. **Right click** and select **New\...REST Client**.

   By default the **General** tab displays.
3. Complete the fields as required.

   For further detail see [General tab](https://help.security.gallagher.com/knowledge-hub/configuration-client/introduction-to-command-centre/knowing-your-way-around/generic-properties-configuration/general-tab.md).
4. Click the **Status and Overrides** tab.

   ![](https://3000903572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCvaxj3suxNBzdwQndVT%2Fuploads%2Fgit-blob-02c478e173f2dd575de011642de19f4dbe550952%2Frestclient_status%26overridestab.png?alt=media)

   REST Clients that use this REST Client item’s API Key can push status updates that will appear on this tab.
5. The Enable offline monitoring check box (disabled by default) allows the REST Client item to enter the ‘Offline’ state if no REST request is received using this REST Client item’s API Key within the configured timeout range.
6. If you selected the Enable offline monitoring check box, enter an Offline timeout. If no request is received for this duration, the REST Client item displays as ‘Offline’.

   (Valid range is 30 seconds - 26 hours)
7. Click the **API Key** tab.

   **Note:** The **API Key** field is only visible if the Configuration Client operator has the 'Advanced User' privilege. REST Clients need this key in order to connect to the REST API.

   ![](https://3000903572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCvaxj3suxNBzdwQndVT%2Fuploads%2Fgit-blob-8b8e5629dbbe07d32537685c14ef99e85e087cce%2F44896.png?alt=media)

   The **API Key** field is populated with an automatically generated secure token for the Rest Client.
8. To require incoming REST connections to be from machines with a client certificate whose thumbprint matches the one entered here, select the **Client Certificate** check box. This increases security by requiring incoming connections to provide an extra level of authentication, and Gallagher recommends this.

   The select whether you will enter the certificate’s thumbprint or import the certificate file.

   <table><thead><tr><th width="160">If you select...</th><th>then...</th></tr></thead><tbody><tr><td>Enter Thumprint</td><td>enter the SHA-384 certificate thumbprint you have been provided, or create one using the <a href="https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item/creating-the-client-certificate.md">Creating the Client Certificate</a> procedure. The certificate thumbprint is found in the <strong>Details</strong> tab of the certificate file. Spaces are allowed, but remove any colons. If you provide a SHA-1 thumbprint, the full certificate is imported on the first connection request, and the SHA-1 thumbprint is replaced with the SHA-384 thumbprint.</td></tr><tr><td>Import Certificate</td><td>Click the <strong>Import</strong> button to upload the client certificate file. This must be a PFX or P12 file. Any private keys or passwords in the file are not saved. If required, create a client certificate using the <a href="https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item/creating-the-client-certificate.md">Creating the Client Certificate</a> procedure.<br><br><strong>Note:</strong> If you do not have a certificate in a PFX/P12 file, (e.g. you have two separate files for the certificate and private key), convert the certificate file to a PFX/P12 file first. This can be done using OpenSSL or other tooling.</td></tr></tbody></table>

   **IMPORTANT:** If the **Enable REST Clients with no client certificate** checkbox (in the [Web Services tab](https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/server-properties/web-services.md)) is left unchecked as recommended, the Client Certificate Thumbprint must be copied from the certificate used by the REST API client and pasted into the **Client Certificate Thumbprint** field. If the **Enable REST Clients with no client certificate** checkbox is checked, the Client Certificate Thumbprint does not need to be entered; but it may be entered. If a Client Certificate Thumbprint is entered, it must match the client certificate (must be valid).
9. The **REST Client Operator** must be a Service Principal or a Cardholder. Gallagher strongly recommends assigning a Service Principal.

   <table><thead><tr><th width="160">To assign a...</th><th>then...</th></tr></thead><tbody><tr><td>Service Principal (recommended)</td><td><ol><li>Click <strong>Manage</strong> from the menu bar, then <strong>Service Principals</strong>.</li><li>From the Service Principal List Window, drag and drop a Service Principal into the <strong>REST Client Operator</strong> field.</li></ol></td></tr><tr><td>Cardholder</td><td><ol><li>Click <strong>Manage</strong> from the menu bar, then <strong>Cardholders</strong>.</li><li>From the Cardholder List Window, drag and drop a Cardholder into the <strong>REST Client Operator</strong> field.</li></ol></td></tr></tbody></table>

   **Notes:**

   * The selected Service Principal (or Cardholder) must be assigned to at least one Operator Group.
   * Only one Service Principal or Cardholder can be added in this field.
   * The REST Client cannot be saved until a REST Client Operator is assigned.
   * The privileges assigned to this Service Principal's (or Cardholder's) group Operator Groups will be applied to the REST session. To maximise security, we recommend giving the REST Client Operator the *minimum* privileges required. If you use a Cardholder, exclude the privileges to use or log onto the Command Centre and Configuration clients.
   * To ensure proper auditing, we recommend that each REST Client uses a different REST API Operator.
   * If you use a Cardholder operator, ensure that the operator for the remote Command Centre server does NOT have the ‘View Alarm’ privilege. Otherwise, “operatorRelogon” and “relogon” errors will be logged to the Command Centre log file.
10. The **Refresh Operator privileges** button makes the REST Client aware of the REST Client Operator's current Operator Privileges. You need to click this button every time you change the REST Client Operator's privileges, or the REST Client will not know about the changes (i.e. the changes will not take effect).

    **Note:** The logged-on Command Centre operator must have the 'Terminate Operator Sessions' Operator Privilege, or clicking this button will have no effect.
11. The **Enable REST Client** checkbox (enabled by default) allows a client to be disabled for diagnostic purposes.

    When disabled (unchecked) the REST client will stop working, and when enabled (checked) again the REST client will resume working.

    Operator events will be recorded when it is changed.

#### Set an IP address range (optional)

This allows sites to set a range of IP addresses using CIDR notation. Only clients that connect using machines within this IP range will be allowed access.

12. Click the **Connections** tab.

    ![](https://3000903572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCvaxj3suxNBzdwQndVT%2Fuploads%2Fgit-blob-fd66e5a06209554ca2c92a3b566c8ddd3a75d909%2Frestclient_ipfilteringtab.png?alt=media)
13. Check the **Enable IP Filtering** checkbox.

    The field below becomes enabled.
14. Enter the IP address range that you want to allow access, using the format given in the example on screen.
15. Tick the **Allow connection via Gallagher API Gateway** checkbox if the site has configured the API Gateway and this REST Client is allowed to connect via the API gateway.

    Before using this feature you need to create a Command Centre Cloud item. See [Connecting to the Cloud](https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/connecting-to-the-cloud.md) for the procedure.

#### Set up End to End Encryption for REST User Codes (optional)

16. Click the **E2E Key** tab.

    ![](https://3000903572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCvaxj3suxNBzdwQndVT%2Fuploads%2Fgit-blob-09bbd1f1c4e1a7473677131d503102dc6eb62289%2Frestclient_e2ekeytab.png?alt=media)
17. Copy the local public key using the Local Public Key copy button ![](https://3000903572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfCvaxj3suxNBzdwQndVT%2Fuploads%2Fgit-blob-ee3635c96bae00985dbc4271c31f86cd2072a583%2F43371.png?alt=media) and paste it into your remote server.
18. Paste the equivalent key from your remote server into the **Remote Public Key** field.

    You are now set up for remote User Codes.
19. You need the "View Encrypted Cardholder User Codes" privilege (not part of "Advanced User") to see the resulting encrypted user code via the REST API.

#### Set up End to End Encryption for REST User Codes (optional)

For the encoding API, E2E must be configured in order for the API response to contain the encoding payload (API will return a misconfiguration message if not configured).

20. Click the **E2E Key** tab.
21. Paste the equivalent key from your remote server into the **Remote Public Key** field.

    You are now set up for API encoding.

    **Note:** The **Local Public Key** isn’t required for the encoding API.
22. You need one of the following privileges to see the resulting encrypted encoding data via the REST API:
    * "Advanced User"
    * "Print/Preview & Encode Card"
    * "Allow Re-Printing and Re-Encoding"
23. Click **OK** to exit and save your changes.

    Click **Cancel** to exit without saving your changes.

    Click **Apply** to save your changes and stay in this window.

### In This Section

* [Creating the Client Certificate](https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item/creating-the-client-certificate.md)
* [Test REST API connectivity with third party system (Chrome)](https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item/test-rest-api-connectivity-with-third-party-system-chrome.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.security.gallagher.com/knowledge-hub/configuration-client/site-installation/services-and-workstations/creating-a-rest-api-client-item.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
