Skip to main content

Core API Guide

The Morio Core API is an OpenAPI v3.1 compliant API internal to Morio and — with the exception of a few endpoints — is not accessible to users.

Core API Reference Documentation

If you are already familiar with the API and are merely looking for answers about which endpoint to use or what data to expect, please refer to /docs/reference/apis/core.

This API is safe to ignore

The most important thing to know about the Core API is that you can safely ignore it. It is internal to Morio, and users or even administrators of Morio should never have to use it.

This guide is intended for (aspiring) contributors, or anyone who would like to gain a deeper understanding of how Morio works under the hood.

Purpose of Morio’s Core API​

Morio’s Core API (the API) provides functionality that spans various domains:

  • Cluster: Accept Morio cluster invites from other nodes, and process the cluster heartbeat
  • Cryptography: Generate X.509 certificates and encrypt or decrypt data on demand
  • Docker: Getting information from the Docker daemon, restarting containers, and other Docker-related tasks
  • Client Packages: Build client packages or provide their defaults
  • Settings: Handle initial setup as well as updates to the Morio settings
  • Status: Provide a consolidated status of all Morio services

Accessing the API​

Most Core API endpoints are not exposed

As this is an internal API, the only endpoints that are available from the network are the /status endpoint and the /cluster/join and /cluster/heartbeat endpoints.

The API itself is available on all Morio nodes, and can be accessed under the prefix /-/core/.

All documentation of API endpoints is relative to this prefix. So to access the /status endpoint of this API on a Morio node, you should use:

https://[your-server-name]/-/core/status

If your server’s DNS name is example.morio.it, you could run the following curl command to get the /status endpoint:

curl https://example.morio.it/-/core/status

Or, if your system does not trust the Morio certificates:

curl --insecure https://example.morio.it/-/core/status

Authentication​

As an internal API, the Core API does not use or support authentication. Most of its endpoints are not available on the network, but only internally.

Given that this API does not use authentication, it is worth going over the routes that are available on the network and explain why no authentication is used:

The /status endpoint​

Just as in the Management API, this is a public and anonymous route, so no authentication is required.

Included in the /status endpoint of the Management API

The Management API includes the core status in its own /status endpoint. So you do not need to hit this endpoint: you can use the regular API and check the core key for the core-specific status.

The /cluster/join endpoint​

Perhaps counter-intuitively, this too is a public or anonymous route. However, it is only available while Morio is running in ephemeral mode. While being in ephemeral mode, Morio will eagerly await either its initial setup or a cluster join request.

In other words, once Morio has received its initial settings, this endpoint will no longer be available and will instead return an error response of type morio.core.ephemeral.required.

The /cluster/heartbeat endpoint​

While this too is a public or anonymous route — by which we mean that no authentication headers are required — the cluster heartbeat payload will be cryptographically signed and verified on each end.

This is done by including a checksum that holds a SHA-256 hash of the combination of the payload data, the Morio Root Token, and the password of the internal secret key.

The checksum will be verified on both ends, thus guarding this endpoint against abuse.