Service Accounts and API Keys
Service accounts and API keys support integrations, connectors, MCP clients, automation, and AI Agent workflows that need to call FactVerse without a human user at the keyboard. They should be treated as production identities with ownership, scope, rotation, and audit expectations.
Use this page when preparing an integration handoff or reviewing whether a non-human identity has the right level of access.
Prerequisites
Confirm the integration owner, target environment, product endpoint, and data boundary before issuing any credential. The customer or project team should also have an approved place to store secrets and a process for emergency revoke.
Identity flow
When to use a service identity
| Scenario | Use |
|---|---|
| Data connector | Pull or push data from an approved source system using a controlled credential. |
| MCP client | Let an AI client discover and call only the FactVerse tools allowed for that endpoint slice. |
| AI Agent workflow | Retrieve approved context, run governed tools, and record workflow actions under a traceable identity. |
| Enterprise automation | Run scheduled imports, exports, report refreshes, or maintenance handoff jobs. |
| System integration | Connect EAM, CMMS, BMS, ERP, data lake, file service, or customer portal workflows. |
Inputs
| Field | Example |
|---|---|
| Business owner | Team responsible for the integration outcome. |
| Technical owner | Team responsible for credential storage, rotation, and incident response. |
| Tenant and environment | Production, staging, private cloud, or on-premises deployment. |
| Endpoint or product area | DFS connector, ECM import, MCP slice, AI Agent workflow, or product API. |
| Required scopes | Read, write, compute, action draft, approval, or product-specific scope. |
| Data boundary | Tenant, site, asset group, folder, dataset, or workflow boundary. |
| Rotation policy | Rotation schedule and emergency revoke procedure. |
Scope design
Start with the narrowest scope that completes the integration. Avoid sharing one key across unrelated systems or tenants.
| Scope decision | Recommended approach |
|---|---|
| Tenant boundary | One key should belong to one tenant or deployment boundary. |
| Product boundary | Separate keys for DFS, ECM, MCP, and AI workflows when ownership differs. |
| Action boundary | Separate read-only keys from keys that can write, approve, trigger actions, or change configuration. |
| Lifecycle | Rotate keys on a schedule, after owner changes, and after any suspected exposure. |
| Storage | Store secrets only in approved secret management or deployment configuration systems. |
Validation checklist
- Confirm the integration can authenticate only against the intended environment.
- Confirm tool discovery or API access returns only the expected capabilities.
- Run one read-only test before enabling write or action scopes.
- Confirm write or action tests create expected audit records.
- Confirm the key owner, rotation owner, and revoke path are documented.
- Confirm the integration fails closed when the key is removed or expired.
Expected result
At handoff, the integration should authenticate only to the intended environment, expose only the expected tools or APIs, create audit records for write or action scopes, and have a documented owner for rotation and incident response.
Operational controls
- Do not embed keys in screenshots, documents, client-side code, or shared chat history.
- Use separate keys for development, staging, and production.
- Review unused keys and remove them.
- Record why a key exists, who owns it, and which workflow depends on it.
- When an AI Agent workflow uses a service identity, keep source data, action scope, and validation handoff explicit.
Related pages
- Use FactVerse MCP Integration Guide for MCP endpoint and key usage.
- Use MCP Scope Reference for scope language.
- Use Authentication Troubleshooting when API calls return authentication errors.