API and authentication
External AI agents reach Pulse through two endpoints:
| Endpoint | Purpose |
|---|---|
GET /mcp/manifest.json | Returns the list of tools the caller is authorized to use. |
POST /mcp/run | Runs a tool and returns the result, or starts an async query. |
Authentication #
An agent authenticates with a static API key sent in the X-Auth header:
curl https://your-instance.example.com/mcp/manifest.json \
-H "X-Auth: <AGENT_API_KEY>"
Each key is bound to a dedicated agent user: a machine identity created when you mint the key. The rule is one key, one agent. The agent user is not a person and cannot sign in to the UI; it exists only to carry the key's authorization.
Agent keys are an Enterprise capability managed in the admin UI under API keys. Creating a key provisions its agent user and lets you assign the groups that define its scope. Deleting the key removes the agent user and its access.
What the agent can do #
The agent's reach is intentionally narrow:
- It sees only the topology tools its groups permit. The instance-wide assistant tools (metrics, docs, onboarding, entity history) are never exposed to an agent. Those belong to the in-app Pulse chat for signed-in people.
- It can run a permitted topology and read its result. Nothing else.
How execution maps identities #
When an agent runs a topology:
- Authorization is checked against the agent user's groups (the same run ACL used across the platform).
- Execution happens under the system identity, so the shared application credentials your connectors use resolve for everyone.
- The real caller is recorded in the audit log and forwarded to the topology in the
identityheader.
This separation is what lets you give an agent access to a process without handing it the credentials behind that process.
Where to go next #
- Manifest and run: the request and response shapes.
- Scoping with groups: grant access to specific topologies.