API keys and the REST API

Scripts, pipelines, monitoring tools and the gdn command-line tool talk to Gardience with an API key. A key always acts as the person who created it, called its owner, and can never do more than that person.

Create a key#

1. Sign out of the console and sign back in. Gardience only lets a session that started on its own sign-in page create keys.
2. Open Settings and find API keys.
3. Enter a name for the key, for example Prometheus or Nightly patch job.

4. Choose a scope:

   • Read only: sees everything the API offers, changes nothing.
   • Operate (request runbooks): can also request runbook runs and upload Ansible playbooks.
   • Configure (Terraform, admins): for Terraform and other infrastructure-as-code tools. Manages enrollments, custom node groups, saved states and event rules, and removes machines. It cannot request runs on the existing fleet. It can, however, decide what happens to new machines: an enrollment lets them join without approval, and a join rule applies a saved state to them (states are still checked by the config keeper, and cannot run commands while command execution is off). Treat it like an admin credential. See Terraform.
5. Leave Require approval ticked unless you have a reason not to (see below).
6. Click Create key.
7. Copy the key. It starts with gdn_ and is shown once. Store it in your secrets manager.

Gardience keeps only a SHA-256 hash of the key. The list shows the first 10 characters so you can tell keys apart, plus the owner, scope, approval setting, last use and expiry date.

Who can do what with keys:

Creating and revoking keys are recorded in the audit log (apikey.created, apikey.revoked).

Approval#

When an operate key has Require approval on, each run it requests waits for a second person. Someone with the admin or approver role approves or rejects it in the console under Workflows. The key's owner cannot approve their own request.

The API answers at once with the run's ID and the status awaiting approval. Poll GET /runs/{id} to follow it.

With approval off, the run starts at once with the status running.

What a key is allowed to run#

Even an operate key can only:

• Request runbooks, the predefined actions listed by GET /runbooks, with inputs that pass the runbook's checks. A key can never run an arbitrary Salt function, and cannot launch workflows.
• Run a runbook on nodes where its owner's own Salt permissions allow that function. Gardience checks this for every target node before anything is queued. A refusal is recorded as api.run_denied.
• Run uploaded playbooks that its owner uploaded.

A key also needs a valid license to request runs. See Licensing.

When a key stops working#

A key is refused with HTTP 401 when any of these is true:

• It was revoked.
• It has expired. Keys created in the console expire 90 days after creation. Create a new one before then.
• Its owner was removed with gardience user del. This takes effect at once.

• Its owner has not signed in to the console recently. This is the idle pause:

  • 30 days for an owner with a local or directory account.
  • 7 days for an owner who signs in through single sign-on, because Gardience cannot see when someone is removed from the identity provider. To change this, add GARDIENCE_SSO_KEY_DAYS=N to the install's .env file and run gardience start.

A paused key works again as soon as its owner signs in. Keys used by monitoring or automation therefore need an owner who signs in regularly.

A read or configure key that tries to request a run gets HTTP 403. A read or operate key that tries to change configuration gets HTTP 403, "This needs a configure key".

Call the REST API#

The base URL is https://<console>/gardience/api/v1. Send the key in the Authorization header:

curl -s -H "Authorization: Bearer gdn_..." https://gardience.example.com/gardience/api/v1/fleet

Interactive documentation, generated from the running server, is at /gardience/api/v1/docs, and the OpenAPI description at /gardience/api/v1/openapi.json. The console links to it from Settings > API keys (API reference).

Endpoints#

All paths are relative to /gardience/api/v1.

Changes made with a configure key are recorded in the audit log under the key's owner, with "via API key NAME".

Request a run#

curl -s -X POST https://gardience.example.com/gardience/api/v1/runs \
  -H "Authorization: Bearer gdn_..." -H "Content-Type: application/json" \
  -d '{"runbook": "run-command", "inputs": {"nodegroup": "Linux", "command": "uptime"}, "reason": "check load"}'

{"run_id": "...", "status": "awaiting approval", "console": "/gardience/workflows#run-..."}

The body takes runbook (a runbook ID from GET /runbooks), inputs (an object) and reason (shown to the approver and kept in the audit log). Every request is recorded as api.run_requested.

Upload a playbook#

POST /playbooks takes name and content:

• name may use letters, digits, ., - and _, up to 64 characters, and must end in .yml or .yaml.
• content must be a YAML list of plays, no larger than 200 KB.

The answer gives a playbook value to pass as the playbook input of the ansible-upload runbook. Uploads are kept per owner and recorded as playbook.uploaded. The gdn playbook command does both steps for you.

Errors#

Errors come back as JSON with a detail message:

The MCP server#

Gardience is also a Model Context Protocol (MCP) server. MCP is an open protocol that lets other tools, such as code editors, call a service's functions. Any MCP client that supports the HTTP transport with a custom header can connect.

• Address: https://<console>/gardience/mcp
• Authentication: the same API key, in an Authorization: Bearer gdn_... header.
• Transport: JSON-RPC 2.0 over HTTP POST, with JSON responses. Batches are accepted. GET returns 405, because the server never starts a stream of its own.

A typical client configuration looks like this (the exact file depends on your client):

{ "servers": { "gardience": { "type": "http",
    "url": "https://gardience.example.com/gardience/mcp",
    "headers": { "Authorization": "Bearer gdn_..." } } } }

The console shows ready-made examples for common clients under Settings.

Tools#

A read key does not see request_runbook in the tool list. request_runbook follows exactly the same rules as POST /runs, including approval, and each call is recorded in the audit log as mcp.request_runbook. A tool's answer is cut off after 60,000 characters.

Related#

• The gdn command line
• Users and roles
• Monitoring
• Licensing