> 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/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-troubleshooting-a-technology.md). # REST API - troubleshooting a Technology Partner integration Isolate REST API integration faults with Technology Partner applications. > 📋 **Prerequisites:** You should already know how the REST API is [set up in Command Centre](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-setting-up-rest-api-in-command-center.md) and what an [API key](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-what-is-an-api-key.md) is. When a **Technology Partner** builds an integration against Command Centre, the failing code is theirs and you cannot see it. This page is the triage method for that fault class. Ground your troubleshooting in what Command Centre can and should be configured to do, then isolate down a fixed ladder. ## Why this fault class is different In a normal Command Centre fault you can see both ends. Here you cannot. Chasing the partner's implementation is unproductive. Invert the question. Instead of asking why their integration is failing, ask whether anything can talk to this Command Centre server correctly. A neutral REST client answers that. Use the **REST sample app** from the Command Centre installation media, or **Postman**. If a neutral client succeeds where their integration fails, the fault is theirs and you can hand it back with evidence. ## The Gallagher token A Technology Partner is issued a Gallagher token. Their integration embeds that token and presents it when the REST client authorizes to the Command Centre server. In Command Centre the credential a REST client presents is the **API key**. It is sent with every request and it combines the username and password of the REST operator. The client prepends `GGL-API-KEY` (with a trailing space) in the HTTP header. That prefix is not part of the key. A missing or unknown key raises **"A REST connection was attempted with an invalid API key"** in the Event Viewer. Because the key carries the operator identity, the REST operator's privileges bound what the integration can do. See [REST API - Create REST Operator](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-create-rest-operator.md). ## What bounds the endpoints Two things decide whether an endpoint is available at all. Both must be satisfied. | Bound | What it is | Where it is set | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | **Licensed edition** | The REST API is sold as five separate editions. Each covers an endpoint family. An unlicensed family does not exist on that server | Site licence | | **Approved endpoint list** | The Technology Partner supplies the list of endpoints their integration will call. Gallagher developers review and approve it. The token is enabled for that set | Partner integration agreement | The five licensed editions: | Edition | Part # | What it does | | --------------------------------------- | ------ | ------------------------------------------------------------------------------------- | | Events & Alarms | C12772 | Retrieve historical and monitor live alarms and events; acknowledge, process, note | | Cardholders | C12784 | Create, modify, delete cardholders; real-time cardholder sync | | View Status | C12810 | Current status of Door, Access Zone, Alarm Zone, Fence Zone | | Overrides | C12812 | Override Door, Access Zone, Alarm Zones, Fence Zones, Macros, Outputs | | Create Events & Alarms (Inbound Events) | C12820 | Receive external events as alarms, instructions, site-plan indications, notifications | > ⚠️ **If the integration calls an endpoint outside the list it originally supplied, it will never work.** No amount of network, certificate, or key troubleshooting fixes it. Rule this in or out early. The resolution is a scoping conversation with the partner, not a support fix. ## Establish the facts first Do not touch configuration until you have these. They decide which branch of the ladder you are on. | Question | Why it matters | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | What is the actual issue? Exact symptom, exact error, HTTP status code, timestamp | A 401, a 403 and a 404 point at three different steps | | What version of Command Centre? | The API surface changes between releases. Endpoints are sometimes deprecated, so the integrator must track the version | | What licences does the site hold? | Each REST API edition is licensed separately | | Is the licence string that enables their integration present? | A missing licence string looks like a broken endpoint but is not one | | Which endpoints is the integration calling? | Compare against the approved list | | Direct on-premises, or through the Cloud API Gateway? | Different failure modes and different things to check. See [Cloud API Gateway](/knowledge-hub/products/cloud-services/cloud-api-gateway.md) | ## The isolation ladder Work top to bottom. Each step only makes sense once the one above it passes. ### Step 1. Connection 1. Browse to `https://:8904/api/`. Ignore the key and the certificate at this stage. 2. Check the Command Centre **Event Viewer**. If the service is listening and the port is open you get **"A REST connection was attempted with an invalid API key"**, with the client IP on the Details tab. That alarm is a good sign. It proves connectivity. 3. Run `Telnet 8904` to confirm the port is open. > ⚠️ **The two trust checks are independent.** The client must trust the server: if it does not, Command Centre never receives a connection and raises no alarm, so the problem is entirely client-side. The server must trust the client: if "Do not require pinned client certificates" is not ticked and Command Centre cannot match a REST Client item, it raises an **"invalid client certificate"** alarm. See [REST API - Certificates](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-certificates.md). ### Step 2. Licence 1. Confirm which REST API editions the site is licensed for. 2. Confirm the licence string that enables the partner integration is present and applied. 3. An endpoint in an unlicensed edition will fail in a way that looks like a bad request. Check the licence before you blame the query. ### Step 3. Token 1. Test the key in the **REST sample app** or in **Postman**. 2. Check the header prefix. The client prepends `GGL-API-KEY` with a space, and the prefix is not part of the key. 3. Check IP filtering on the REST Client item. A space is as good as a comma in that field. 4. Check the **Client Certificate Thumbprint** if pinned client certificates are required. 5. Remember the key carries the operator identity, so the REST operator's privileges apply on every call. ### Step 4. Endpoint 1. Cross-check the endpoint the integration calls against the list the partner supplied and Gallagher approved. 2. Cross-check it against the licensed editions above. 3. Out of scope on either check means the call cannot succeed. Stop troubleshooting and take it back to the partner. ### Step 5. Query 1. Reproduce the same call in Postman or the REST sample app. If it succeeds there, the fault is in how their integration builds or sends it. 2. Check for **HTTP 409 Conflict**. That is optimistic concurrency. The integrator must refetch, reapply and retry. 3. Check the payload for malformed or missing fields. 4. For deeper diagnosis, turn on REST logging. `RESTAccess.log` (vEL8.90 and later, via the `LogRESTRequests` registry key) records every public-API call. The main log is at `C:\ProgramData\Gallagher\Command Centre\Command_centre.log`. See [REST API - Logs](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-logs.md). ## Reading the result | Neutral client (sample app or Postman) | Their integration | Conclusion | | ------------------------------------------- | ----------------- | ------------------------------------------------------- | | Cannot connect | Fails | Network, port, certificate or server-side. Ours to fix | | Connects, fails on the key | Fails | Token, IP filtering or client-certificate configuration | | Works on the main endpoint, fails on theirs | Fails | Licence, or an endpoint outside the approved list | | Works on the same endpoint | Fails | Their integration. Token handling or query construction | ## Handing it back When the fault is on the partner's side, hand it back with evidence rather than a verdict. Send: * The working request from Postman or the REST sample app. * The response you received. * The matching Command Centre Event Viewer entry, or the `RESTAccess.log` line. That turns "it does not work" into a specific difference the partner can act on. *** 🔗 **Related** * [REST API - Connection](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-connection.md). The connection checks and what each alarm means. * [REST API - What is an API Key?](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-what-is-an-api-key.md). The invalid-key alarm explained. * [REST API - Certificates](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-certificates.md). The invalid-client-certificate alarm explained. * [REST API - Features](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-features.md). What the licensed editions cover. * [REST API - Logs](/knowledge-hub/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-logs.md). Turn on logging for deeper diagnosis. --- # 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/products/cc-software/configure/interface-options/api/representational-state-transfer-rest-api/rest-api-troubleshooting-a-technology.md?ask=&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.