Machine-to-machine API keys
Scope catalog
The grantable catalog comes from mounted REST @Scopes() declarations and App-provided
M2M_SCOPE_SOURCES (ScopeSource[]). Concrete scopes use <resource>:<action>, split at the
last colon. Each resource segment and the action must contain only [a-z0-9_-], with at
least one character per segment. For example, users:read, haneinfo-reports:definition:read
and haneinfo-reports:reports:data:read are valid when declared. Empty segments, whitespace,
uppercase characters and embedded wildcards are rejected. Actions are not limited to read/write.
New grants must be declared concrete scopes, * (the existing global grant), or
<resource>:* for a resource with at least one concrete catalog entry. A wildcard declaration
alone does not establish a resource. Resource matching is exact: haneinfo-reports:definition:*
matches haneinfo-reports:definition:read, whereas haneinfo-reports:* does not. The latter
cannot be issued unless a concrete scope with resource exactly haneinfo-reports is declared.
list() returns sorted concrete scopes; describe() and groupOf() use the entire resource
for App M2M_SCOPE_GROUPS display grouping. Key creation validates all grants; updates validate
only newly added grants, preserving existing legacy scopes through unrelated edits. ScopeGuard
and the SCOPE_MATCHER capability used by MCP delegate matching to plugin-api matchScope.
See the agent guide for App wiring and verification.
Authentication observation
Successful API key authentication records lastUsedAt asynchronously. Writes are throttled per key across processes using a conditional database update. The default interval is 60 seconds; set M2M_API_KEY_LAST_USED_INTERVAL_SECONDS to an integer from 0 to 86400 to change it (0 disables throttling). Invalid or absent values use 60 seconds. The timestamp can lag the latest successful authentication by up to the configured interval, plus asynchronous database delay; write failures are logged and retried on a later request. This timestamp is observational and does not determine authentication or authorization.