The REST API

Everything the web interface does, something else can do too. The API is under /api/v1, and a call carries a personal access token from Profile, API tokens as HTTP Basic credentials: the username, and the token in place of a password. The token must belong to the username sent with it, or the call is refused.

curl -s https://dutest.example.com/api/v1/plans \
  -u "$DUTEST_USER:$DUTEST_TOKEN"

The reference is generated from the server's own request mappings, so it cannot describe an endpoint the server does not serve. The same document is at openapi.yaml, as OpenAPI 3.1, which is what a client generator reads.

Your own server carries the same two things, for the version it runs:

• /swagger-ui.html — every endpoint, on a page you can call them from. Paste a token into Authorize and the page calls as you.
• /v3/api-docs — the document as JSON, and /v3/api-docs.yaml as YAML.

Both are readable without signing in. They publish the shape of the API rather than anybody's data, and deciding whether to integrate should not require an account. The endpoints themselves are unaffected: they answer 401 without a token and 403 to a token whose owner may not do that.

Tokens

A token is shown once, when it is created, and stored hashed. It acts as the account that made it, with that account's permissions, and is revoked from the same page. A script that installs or configures a server wants one of these rather than a password: it can be rotated without changing the password anybody signs in with, and revoked without locking anybody out.

Two other tokens exist and are not for calling the API with. An agent enrolment token is spent on an agent's first connect, and the cluster join token is a shared secret between the controller and its agents. Install and run says where each is used.