Direct Agent API
Give trusted staff agents direct HTTP access to the LedgerHQ admin API.
LedgerHQ supports a direct API option for trusted staff agents that prefer HTTP requests over the Codex plugin or an MCP connector.
Use this path for agents such as Hermes when they need admin/support operations and already have secure secret storage. Use the Codex plugin or remote MCP for normal bookkeeping work inside the approved accounting tool surface.
Direct admin-agent keys are powerful staff access keys. Create them only from the staff admin panel, map them to a real site-admin actor, and revoke them from the same screen when they rotate or are no longer needed.
Access Choices
| Option | Best for | Auth |
|---|---|---|
| Codex plugin | Codex bookkeeping agents with LedgerHQ skills | LedgerHQ MCP agent token in LEDGERHQ_MCP_TOKEN |
| Remote MCP | Claude and other MCP-native bookkeeping agents | LedgerHQ OAuth MCP |
| Direct Admin API | Trusted staff agents that prefer HTTP, such as Hermes | Admin bearer key |
Create A Direct API Key
- Sign into LedgerHQ as a site admin.
- Open
/admin/agent-access. - Click
New Key. - Choose the staff/site-admin actor the agent should run as.
- Copy the one-time secret or setup block.
- Store the secret in the agent environment as
LEDGERHQ_ADMIN_AGENT_TOKEN.
Raw secrets are shown only once. LedgerHQ stores only the hashed key.
Bootstrap The Agent
Every direct API agent should start with the capabilities endpoint:
curl https://ledgerhq.pro/api/v1/admin-agent/capabilities \
-H "Authorization: Bearer $LEDGERHQ_ADMIN_AGENT_TOKEN"The response verifies the token and returns:
- the key label and actor email
- granted scopes
- the admin API base path
- an inline
reference.routeGroupsmap of supported admin routes - next actions the agent should follow before making calls
The optional refresh endpoint returns the same curated route reference:
curl https://ledgerhq.pro/api/v1/admin-agent/reference \
-H "Authorization: Bearer $LEDGERHQ_ADMIN_AGENT_TOKEN"Agents should not fail setup if this refresh endpoint is unavailable after a successful capabilities call.
Call Admin Routes
Admin routes are nested under /api/v1/admin. Do not guess root paths such as
/tickets, /billing, /chats, or /plaid.
Example:
curl https://ledgerhq.pro/api/v1/admin/support/tickets \
-H "Authorization: Bearer $LEDGERHQ_ADMIN_AGENT_TOKEN"Use IDs returned by list/detail routes before mutating records, and prefer ticket-system replies for user support.
Scope Boundary
The current direct API scope is broad admin:*, matching site-admin API access.
The capabilities response lists scope metadata and is the source of truth for
future narrower route scopes.
Direct API keys cannot create or revoke other direct API keys. Key creation and
revocation require a signed-in human site admin at /admin/agent-access.