Canonical API Endpoint Hosts

Technical reference for the immutable, hardcoded endpoint hosts the product uses for outbound calls to the central control plane for licensing, updates

Overview

This document provides a reference for the canonical server-to-server endpoint hosts used by the product for all outbound communication with the central platform. These endpoints facilitate critical operations such as license validation, software update checks, heartbeat monitoring, and telemetry data export.

The endpoint hosts are defined as immutable constants compiled directly into the product binary. This is a deliberate design choice to ensure stability and prevent configuration drift across different customer deployments. By hardcoding these values, every deployment—whether self-hosted or SaaS—communicates with the correct, globally consistent control plane. This design eliminates a class of potential silent failures that could arise from misconfigured or stale endpoint addresses, which could otherwise lead to degraded entitlement enforcement or fail-open telemetry.

The only per-deployment variations are the deployment's unique identity and credentials (e.g., deployment ID, API key, installation ID), not the platform hosts themselves.

How It Works

The system defines a set of public static final string constants within the SpecariaEndpoints component, which serve as the single source of truth for all outbound API calls. There are two primary communication planes, each with a distinct base hostname:

Public API Plane (https://api.specaria.io): This is the main integration plane for most server-to-server interactions.
mTLS Plane (https://updates.specaria.io): This plane is used exclusively for polling channel-gated release manifests, secured with mutual TLS.

A third hostname, https://license.specaria.io, is defined for validating the iss (issuer) claim in license JWTs, but it is not an endpoint that the product makes outbound calls to.

IMPORTANT

These endpoint hosts are immutable and cannot be overridden. The product does not read any environment variables or configuration properties to determine these values. All deployments use the same canonical hostnames.

Development and testing environments achieve connectivity to non-production control planes by using private DNS to resolve the canonical hostnames to the appropriate development infrastructure. This is an infrastructure-level concern and does not involve changing the product's configuration.

The following diagram illustrates the flow of outbound communication from a product deployment to the central API planes.

flowchart TD
    subgraph Product Deployment
        A[Product Instance]
    end

    subgraph Central Platform
        B[Public API Plane<br>api.specaria.io]
        C[mTLS Plane<br>updates.specaria.io]
    end

    A -- "Licensing, Heartbeat, Telemetry, Settings, etc." --> B
    A -- "Release Manifest Poll" --> C

Endpoint Reference

The product uses a combination of fully-resolved URLs and base URLs to which specific paths are appended by the client-side logic.

Canonical Base Hosts

These are the fundamental, hardcoded base hosts for all platform communication.

Hostname	Constant	Purpose
`https://api.specaria.io`	`PUBLIC_API_BASE`	Public integration plane for licensing, heartbeats, settings, telemetry, and other general API interactions.
`https://updates.specaria.io`	`MTLS_PLANE_BASE`	mTLS-secured plane used exclusively for polling channel-gated software release manifests.
`https://license.specaria.io`	`LICENSE_ISSUER`	A value used to verify the `iss` (issuer) claim in a license JWT. The product does not make network calls to this host. Its inclusion is for reference and validation logic.

Full Endpoint URLs

These are complete, static URLs constructed from the base hosts.

Purpose	Constant	URL
JWKS Public Keys	`JWKS_URL`	`https://api.specaria.io/v1/license-public-keys/s2r`
License Request Submission	`LICENSE_REQUEST_URL`	`https://api.specaria.io/v1/license-requests`
Debug Bundle Registration	`DEBUG_BUNDLE_URL`	`https://api.specaria.io/v1/products/s2r/debug-bundles`
Debug Bundle Encryption Public Key	`DEBUG_BUNDLE_PUBKEY_URL`	`https://api.specaria.io/v1/debug-bundle-public-keys/s2r`
Usage/Metering Export	`USAGE_EXPORT_URL`	`https://api.specaria.io/v1/products/s2r/usage`
General Product Feedback	`FEEDBACK_URL`	`https://api.specaria.io/v1/feedback`
Documentation AI Assistant Chat	`ASSISTANT_CHAT_URL`	`https://api.specaria.io/v1/products/s2r/assistant/chat`
Documentation AI Assistant Feedback	`ASSISTANT_FEEDBACK_URL`	`https://api.specaria.io/v1/products/s2r/assistant/feedback`

URL Templates

These URLs contain placeholders that are substituted by the calling code before the request is made.

Purpose	Constant	URL Template	Placeholders
License Heartbeat	`HEARTBEAT_URL_TEMPLATE`	`https://api.specaria.io/v1/licenses/{jti}/heartbeat`	`{jti}`: The JWT ID of the license.
Platform Settings Pull	`SETTINGS_URL_TEMPLATE`	`https://api.specaria.io/v1/products/{product_id}/installations/{installation_id}/settings`	`{product_id}`, `{installation_id}`

Base URLs for Client-Side Path Construction

For some operations, the SpecariaEndpoints component provides only the base URL. The client code is responsible for appending the correct path.

Purpose	Method	Base URL	Client-Appended Path Example
Self-Identified License Acquisition	`licenseAcquireBaseUrl()`	`https://api.specaria.io`	`/v1/products/{product_id}/deployments/{deployment_id}/self-id-license`
Update/Release Manifest Poll	`updateManifestBaseUrl()`	`https://updates.specaria.io`	`/v1/channels/{channel}/products/{product_id}/release-manifest`

Prohibited Practices

To ensure reliable operation and forward compatibility, adhere to the following rules:

Do not use regional hosts: The product must never be configured to call regional variants of the API hosts (e.g., a host with a region token like us-east-1 in the subdomain). All communication is routed through the global endpoints listed above.
Do not call operator-only hosts: The product must never make calls to admin-ops.specaria.io, as this host is reserved for internal operational use.

Tagsguides

All SOAP-to-REST docs