# Integration Connections API

The Integration Connections API lets an API Client discover whether organization-level provider connections are ready for an operation. It never exposes provider credentials.

## Connection model

API Clients may use durable connections owned by the organization when the relevant Eos workflow permits. They may not use a member's personal connection, personal mailbox, or personal OAuth token. A provider connection and an Eos API Client are separate credentials with separate lifecycles.

## Roles

Connections are visible only when relevant to a Role held by the API Client. Finance can inspect accounting readiness; Manager can inspect operational integrations. Secret material, refresh tokens, raw provider access tokens, and sensitive provider metadata are never returned.

## List and get connections

- `GET /v1/integration-connections` — `listIntegrationConnections`
- `GET /v1/integration-connections/{connection_id}` — `getIntegrationConnection`

```json
{
  "object": "integration_connection",
  "id": "icn_01J8RC7HW4FMW2FBA7CH7ABN9Z",
  "provider": "quickbooks_online",
  "category": "accounting",
  "ownership": "organization",
  "status": "connected",
  "capabilities": ["invoice.export", "payment.read"],
  "last_success_at": "2026-08-22T08:42:00Z",
  "action_required": null
}
```

Provider names and capabilities are descriptive, not authorization grants. The Eos operation must still be allowed by the API Client's license and Roles.

## Check readiness

`POST /v1/integration-connections/readiness`

Operation ID: `checkIntegrationConnectionReadiness`.

```json
{
  "capability": "invoice.export",
  "resource": {"type": "invoice", "id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S"}
}
```

Returns whether an eligible organization connection is available, plus safe remediation text for an administrator. It does not perform the operation.

## Unsupported operations

Creating, authorizing, reconnecting, reconfiguring, or deleting provider connections is not part of v1. Those operations require an interactive administrator and the provider's authorization flow.

## Common errors

`INTEGRATION_CONNECTION_NOT_FOUND`, `INTEGRATION_CONNECTION_NOT_READY`, `CAPABILITY_NOT_AVAILABLE`, `PERSONAL_CONNECTION_NOT_ALLOWED`, and `ROLE_REQUIRED`.

Next: [Agents API](agents.html).