External Connection Identities

An External Connection is the safe boundary between one outside client and your LeenOps workspace. Use one connection for each agent, application, or deployment so you can identify, restrict, rotate, and revoke it independently.

No manual user account is required

When an Owner or Admin creates an External Connection, LeenOps automatically creates a non-login service identity with the same display name. You do not need to invite a bot user, create a mailbox, or assign a workspace seat.

The connection contains four separate concepts:

Rotating the API key keeps the same service identity and history. Revoking the connection disables both the credential and its service identity.

Normal tools and person-bound tools

Most operations run directly as the service identity. This includes contacts, companies, documents, contracts, forms, projects, and other workspace records. Document ownership, access grants, revisions, restore history, and links retain the service identity as their actor.

A small set of operations is inherently about a person, for example my tasks, my active timer, or my time entries. These operations require the connection's optional Allow person-bound tools to run as me setting. Without that setting, the tool returns:

{
  "error": "This person-bound action requires explicit user delegation on the External Connection.",
  "code": "human_delegation_required",
  "requestId": "request-uuid"
}

Do not create a fake employee or bind every connection to the workspace owner. Delegation is explicit because the personal action should be attributed to the selected person; all connection activity still records the service identity and credential separately.

Recommended setup for a nontechnical user

1. Open Settings > Administration > API & MCP.
2. Select Create External Connection.
3. Name it after the client, such as Hermes Production or Claude Desktop.
4. Start with Read Only or the smallest relevant permission preset.
5. Leave Allow person-bound tools to run as me off unless the integration actually needs a tool described as my ....
6. Set an expiry for tests or temporary contractors.
7. Create the connection and copy the key once into the client's secret or MCP configuration screen. Never paste it into a chat.
8. Verify the connection with GET /api/mcp/session, then run a read-only tool.

Only an Owner, Admin, or custom role with platform administration access can manage External Connections.

Inspect the active identity

curl "https://workspace.leenops.com/api/mcp/session" \
  -H "Authorization: Bearer $LEENOPS_API_KEY"

Relevant response fields:

{
  "ok": true,
  "apiKeyName": "Hermes Production",
  "workspaceId": "workspace-uuid",
  "principal": {
    "id": "principal-uuid",
    "type": "service",
    "displayName": "Hermes Production"
  },
  "delegation": {
    "mode": "service_principal"
  }
}

If delegation is enabled, delegation.mode is user and includes its user ID. The human who created the connection is not returned as its runtime actor.

Audit and troubleshooting

Every MCP call is correlated with the workspace, service identity, API-key ID, request ID, tool, channel, outcome, and affected entities. Secrets and sensitive arguments are redacted. Include the X-Request-Id response header or requestId error field in a support request; never include the API key.