REST APIs

Horizon exposes a REST API that lets you automate certificate lifecycle management and integrate Horizon with your own systems. Almost anything you can do in the web interface — search your inventory, enroll and renew certificates, run discovery, manage configuration — can be driven programmatically.

This page introduces the concepts you need before you start. The API reference documents every endpoint, parameter, and response in detail; this page is the orientation that comes before it.

API Guides

Download OpenAPI Specification

What you can do with the API

The API is organised around the same objects you work with in the interface:

• Certificates — search the inventory, retrieve details, and download certificates.
• Requests (lifecycle) — enroll, renew, revoke, update, and recover certificates, and approve or deny pending requests.
• Discovery — run discovery campaigns and read discovered certificates and events.
• Profiles — read the certificate profiles that govern how certificates are issued.
• Automation — manage the datasources, notifications, and triggers that connect Horizon to external systems.
• Reporting — build and export reports and dashboards, and reuse saved queries.
• Audit — read the audit event trail.

How the API works

The API is REST over HTTPS and exchanges JSON. Each object type has its own set of endpoints, and standard HTTP methods are used to read and act on them. The base URL and the exact endpoint paths for your tenant are listed in the API reference.

Authentication

Every request must be authenticated. API access uses credentials issued within your tenant; include your credential with each request as described in the API reference.

Treat API credentials like passwords:

• Store them securely and never commit them to source control or embed them in client-side code.
• Issue a separate credential per integration so it can be rotated or revoked independently.
• Grant each credential only the permissions its integration actually needs (see below).

Permissions and scopes

API access is governed by the same role-based permissions as the web interface. Permissions are grouped into three scopes:

• lifecycle — certificate enrollment, renewal, revocation, and related requests.
• discovery — discovery campaigns and discovered certificates.
• configuration — profiles, datasources, notifications, and other tenant configuration.

A credential can only call the endpoints its permissions allow. If a call is rejected for authorisation, the credential is missing the required permission — this is different from a malformed request, which is a syntax problem with the call itself.

Searching with query languages

Search endpoints use Horizon's own query languages rather than free-form filter parameters:

• HCQL for certificates
• HRQL for requests
• HEQL for audit events
• HDQL for discovery events

These use lowercase field names and word operators (equals, contains, before, after, in, is) rather than SQL-style syntax. For example:

keytype equals "RSA" and valid.until before 30d

A malformed query is rejected with an HQL-001 error and the position of the problem. See the Troubleshooting guide for the most common query mistakes.

Requests, responses, and errors

Requests and responses are JSON. Errors return an appropriate HTTP status code along with a machine-readable error code (for example HQL-001) and a message describing the problem. Check the error code first — it identifies the cause precisely and is the fastest way to diagnose a failed call.

Endpoints that return collections are paginated. Use the pagination parameters documented in the API reference to page through large result sets rather than requesting everything at once.

Synchronous and pending operations

Lifecycle operations behave the same way through the API as in the interface. Depending on the calling credential's permissions, an operation either completes immediately or creates a pending request that an authorised operator must approve. When you automate issuance or revocation, design your integration to handle the case where a request is pending rather than already complete, and to check its status before assuming success.

Enrollment protocols

Alongside the management API, Horizon supports standard enrollment protocols — ACME, EST, and SCEP — for clients and devices that enroll directly. These are separate protocol endpoints with their own conventions and are distinct from the REST management API described here. Use them when a client speaks one of these protocols natively; use the REST API to orchestrate and manage the wider lifecycle.

Getting started

1. Obtain an API credential for your tenant, scoped to only the permissions your integration needs.
2. Note the base URL for your tenant from the API reference.
3. Make a read-only call first — for example a certificate search — to confirm authentication and connectivity before performing any lifecycle action.
4. Build out your integration, handling pagination, error codes, and pending requests as described above.

Next steps

Continue to the API reference for the full list of endpoints, their parameters, and example requests and responses.