The manager REST API and programmatic access

Advanced⏱ ~17 mincephcurl

What you'll learn

Describe how the REST API authenticates
Scope automation credentials
Handle token lifecycle
Choose between the API and the CLI for automation

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

Automation credentials are long-lived, widely copied, and rarely reviewed, which makes their scoping the thing that bounds an automation compromise.

How the API authenticates

The manager's REST API is served by the dashboard module and uses the
same account system: a username and password exchanged for a bearer
token.

ceph mgr services

# Substitute the active manager's address before running:
MGR_HOST=192.0.2.11

TOKEN=$(curl -sk -X POST "https://$MGR_HOST:8443/api/auth" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.ceph.api.v1.0+json' \
  -d '{"username":"automation","password":"..."}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])')

# $TOKEN comes from the request above
MGR_HOST=192.0.2.11

curl -sk "https://$MGR_HOST:8443/api/health/minimal" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/vnd.ceph.api.v1.0+json'

The token is a bearer credential with a lifetime. The password that
obtains it is the long-lived secret and is what needs protecting.

Scoping automation

ceph dashboard ac-role-show

# a role limited to what the automation actually does
ceph dashboard ac-role-create metrics-reader
ceph dashboard ac-role-add-scope-perms metrics-reader monitor read
ceph dashboard ac-user-create automation -i /path/to/pw metrics-reader

Automation task	Scope needed
Reading health for a status page	monitor read
Collecting pool statistics	pool read
Creating RBD images	rbd-image create, read
Managing RGW users	rgw read, create, update
Anything else	whatever it actually does, nothing more

An automation account with the administrator role is the same exposure
as an admin keyring in a script, with the addition that it is reachable
over the network.

Token lifecycle

ceph dashboard get-jwt-token-ttl
ceph dashboard set-jwt-token-ttl 600

Aspect	Consideration
Token lifetime	shorter limits a captured token’s usefulness
Password rotation	the long-lived secret; rotate on a schedule
Token storage	in memory, never written to disk
Logging	ensure tokens are not logged by the client
Revocation	changing the password invalidates future logins, not existing tokens until they expire

# revoking access: disable the account
ceph dashboard ac-user-disable automation

Disabling the account is the immediate revocation. Changing the password
alone leaves any already-issued token valid until its TTL expires.

API versus CLI for automation

Approach	Suits
REST API with a scoped dashboard account	automation running off-cluster
CLI with a scoped cephx entity	automation running on a cluster host
CLI with `client.admin`	nothing

# the CLI equivalent, with a scoped entity
ceph -n client.automation -k /etc/ceph/ceph.client.automation.keyring \
  health detail --format json

Where the automation can run on a host with a scoped keyring, the CLI
path avoids the network-reachable credential entirely.

Quiz

Knowledge check · 4 questions

Q1. How do you immediately revoke a compromised API token?

Change the account password, which invalidates every bearer token issued against the previous password the moment the change commits Restart the active manager, since the dashboard module holds its issued tokens only in the process memory Disable the account — changing the password prevents future logins but leaves issued tokens valid until their TTL expires Reduce the JWT token TTL, which re-evaluates every outstanding token against the shorter lifetime at once
Q2. The REST API is the preferred automation path in all cases.

True False
Q3. Set up automation access to a cluster.

A status page running off-cluster needs to display Ceph health. The proposal is an API account with the administrator role.
Q4. When does the REST API earn its place over a scoped cephx entity?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Prefer a scoped cephx entity over an API account where the automation can run on a host that legitimately holds a keyring — the capability model is finer-grained and a file is not network-reachable. Set a short token TTL, and revoke by disabling the account rather than changing the password.

Cross-course references

Kubernetes: ServiceAccount tokens and bearer-token revocation behave the same way
Linux: a credential bounded by file presence has a smaller blast radius than a network one