API Overview

Clients communicate with ConfigHub Cloud via a HTTP REST API. This page gives you an overview of how the API is structured. You can find the complete reference for the API in the OpenAPI Spec at https://hub.confighub.com/api/docs.

Authentication

For endpoints that require authentication, the API requires a valid JWT bearer token in the Authorization header of the HTTP request. There is currently no official documentation for how to obtain a token, but you can read the source code of the CLI to see how it obtains a token.

Writing clients

We generate Go and Typescript client libraries from our OpenAPI spec. The Go client is used in the CLI, cub, which you can use as an example client. You can find the client libraries and cub source code in the https://github.com/confighub/sdk repo.

All details for writing clients are encoded in the OpenAPI Spec at https://hub.confighub.com/api/docs and will not be repeated here. Please use the spec to generate clients or refer to the spec for details when hand writing clients.

JSON format conventions

JSON structures use PascalCase for field names and string constant names. For example:

{
  "OrganizationID": "123",
  "Slug": "a-record",
  "CreatedAt": "..."
}

URL Structure

The URL structure of the REST API reflects the nested collections topology of entities in ConfigHub. Collection names are singular nouns rather than plural. IDs are used as identifiers in URLs. The organization comes from the authentication context, since one logs in as a member of a specific organization.

This will fetch a unit:

GET /api/space/55ec4079-5b96-44f6-9a02-d6bf74286e1e/unit/9872639e-373e-4839-8566-51a928bb8f3d

ConfigHub checks that the URL pattern matches the current state of an entity. For example, in the URL above, if the Unit with UUID 9872639e-373e-4839-8566-51a928bb8f3d exists but is not in the space with UUID 55ec4079-5b96-44f6-9a02-d6bf74286e1e, then the request returns 404 not found even though the Unit does exist.

ConfigHub will also check access permissions and return 403 forbidden if an operation is not permitted by the currently authenticated principal.