Authentication

Authentication

How the CLI proves who it is, and which credential each command needs. The API makes every authorization decision; the CLI only picks one credential and sends it. Where that credential comes from is covered in Configuration.

Credentials

Credential	Source	Header sent
Scoped API key	REPORTMATE_API_KEY, the app's Keychain item, or the Windows runner's ReadApiKey	X-API-Key
OIDC bearer token	REPORTMATE_TOKEN, or minted by az account get-access-token for the Entra audience	Authorization: Bearer <token>
Shared passphrase	REPORTMATE_PASSPHRASE, the app's Keychain item, the runner's preferences, or AWS Secrets Manager	X-Client-Passphrase
Internal secret	REPORTMATE_INTERNAL_SECRET only	X-Internal-Secret

Exactly one of the first three is sent. In the environment the order is API key, then token, then passphrase. The internal secret, when set, is added to every request alongside it.

A scoped API key is the preferred credential. An Entra sign-in needs no stored secret at all: the CLI asks az for a token each time it runs.

API key format

A key looks like rm_<id>_<secret>. The id is a public lookup handle; the secret is stored by the API only as a hash, so the full key is returned exactly once, by api-keys create.

reportmateutil api-keys create ci-reader --scope read

Use the whole key as REPORTMATE_API_KEY. Use the separate id field from the same response to revoke it later.

Scopes

The API defines three scopes and derives the one a request needs from its method and path.

Scope	Covers
read	GET requests
ingest	POST requests outside /admin
admin	Any path containing /admin, plus every PUT, PATCH and DELETE

Mapped onto the CLI:

Commands	Scope
devices, device (read subcommands), module, apps, certificates, logs, events, events failures, events payload, dashboard, metrics, negotiate, admin debug-database, settings get	read
health	none at the API; the CLI still resolves a credential before sending it
events submit	ingest
device … archive, unarchive, delete	admin
api-keys …, admin usage-history …, admin installs …	admin
settings set, settings discover	internal secret; no scope is sufficient
raw	depends on the method and path

API keys are the only scope-limited credential. The API grants the shared passphrase and the internal secret every scope, so a passphrase can run destructive admin commands. A bearer token's scopes come from its roles, groups or scp claims as mapped by the API's OIDC settings.

Because the internal secret is a full-access credential sent on every request, set it only in the shell where you run settings set or settings discover.

Recommended setup

1. Use a read-only key, or Entra sign-in, for day-to-day querying.
2. Keep a separate admin-scoped key out of your default shell profile for lifecycle, api-keys and admin work.
3. Give each automation its own named key so one can be revoked without affecting the others.

reportmateutil api-keys create fleet-audit --scope read

What the CLI does not do

• It never writes a credential anywhere. It reads the app's Keychain item but does not create or change it.
• It does not take a credential from a flag or stdin.
• It does not redact error output: an error includes the full upstream response body.
• It does not check a credential before running a command; an invalid one surfaces as a 401.