> ## Documentation Index > Fetch the complete documentation index at: https://developers.pleo.io/llms.txt > Use this file to discover all available pages before exploring further. # Integrated API Keys Overview export const IntegratedApiKeysOverviewDiagram = () => { const [isDark, setIsDark] = useState(false); useEffect(() => { const check = () => setIsDark(document.documentElement.classList.contains("dark")); check(); const observer = new MutationObserver(check); observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] }); return () => observer.disconnect(); }, []); const nodeFill = isDark ? "#212222" : "#EEF4F4"; const nodeStroke = isDark ? "#848989" : "#E1E6E6"; const nodeTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414"; const subgraphFill = isDark ? "#131414" : "#ffffff"; const subgraphStroke = isDark ? "#848989" : "#6B7070"; const subgraphTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414"; const pleoSubgraphTextStyle = ",color:#FEB6FE"; const linkStyle = isDark ? "" : "linkStyle default stroke:#848989,stroke-width:1px;"; const themeVariables = { ...isDark ? {} : { edgeLabelBackground: "#FAFCFC" } }; const diagram = ` %%{init: {"themeVariables": ${JSON.stringify(themeVariables)}}}%% flowchart TD %% Swimlanes / Roles subgraph Dev[Integration Developer] A1[Request access to build integration] --> A2[Provide integration details to Pleo] end subgraph Pleo["Pleo Platform"] B1[Confirm eligibility for Integrated API Keys] --> B2[Configure integration with pre-scoped permissions] B3[Generate customer-specific Integrated API Key during install] end subgraph Customer["Customer"] C1[Initiates installation via Marketplace or Accounting settings] C2[Receives Integrated API Key] C2 --> C3[Enters key into integration secure input field] end subgraph Integration["Integration System"] D1[Validate key with test API call] --> D2{Validation successful?} D2 -- Yes --> D3[Store key securely & persist company_id] --> D4[Integration active for customer] D2 -- No --> D5[Show clear error & allow retry] D4 --> D6[Ongoing maintenance: rotation, re-validation per customer] end %% Styling for wrapping style A1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style A2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style B1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style B2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style B3 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style C1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style C2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style C3 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style D1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style D2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style D3 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style D4 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style D5 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} style D6 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle} %% Make subgraphs transparent with black borders style Dev fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle} style Pleo fill:${subgraphFill},stroke:${subgraphStroke}${pleoSubgraphTextStyle} style Customer fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle} style Integration fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle} %% Connections across roles A2 --> B1 C1 --> B3 B3 --> C2 C3 --> D1 ${linkStyle} `; return ; }; export const WarningCallout = ({title, children}) =>
{title &&
{title}
}
{children}
; Integrated API Keys provide a **pre-scoped, company-level credential** for accounting or ERP integrations that **cannot support OAuth 2.0**. They are generated by Pleo during the integration install flow and are designed for **per-customer, per-installation connections**. Unlike OAuth 2.0, there is **no redirect, auth code, or token lifecycle** to implement. The key is tied to the customer installation and [pre-configured scopes](/docs/current/authentication/api-scopes). Integrated API Keys [**require approval**](/docs/current/getting-started/developer-partnership-programme#integrated-api-keys-approved-exception-only) from Pleo. They are typically used only for **accounting/ERP integrations** where OAuth 2.0 is not feasible. Integrated API Keys are **restricted** and are **not self-service**. If you’re considering using them, note: * Integrated API Keys are **granted case-by-case** during onboarding * Only approved accounting or ERP integrations can use them * Each key is **tied to a specific customer installation**; it is not a generic API key ## Concepts and Terminology | **Concept** | **Term** | **Description** | | ------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Company credential | **Integrated API Key** | A secret key generated during installation of a Pleo-approved integration, scoped to a single customer installation. Each customer receives a unique key. | | Integration configuration | **Auth client / Marketplace entry** | Defines the scopes and permissions pre-configured into the key by Pleo. Managed internally by Pleo; no OAuth 2.0 client lifecycle exists. | | Permission boundary | **Scoped access** | The set of [API actions](/docs/current/authentication/api-scopes) the integration is allowed to perform. Pre-configured at install time. | | Company identity | **Company\_id** | Identifies the Pleo company whose data the integration can access. | Integrated API Keys represent **direct, pre-approved access** for an integration to act on behalf of a customer installation. They are **per-installation credentials**, meaning each customer gets a unique key. Integrations can therefore support **multiple customers** by storing and managing one key per customer. ## When to Use Integrated API Keys Use Integrated API Keys if: * Your integration **cannot support OAuth 2.0** * You are building an **approved accounting/ERP integration** * You need **pre-configured permissions** without implementing token flows * You are prepared to manage **per-customer keys** for a multi-customer integration Otherwise, [OAuth 2.0](/docs/current/authentication/oauth/oauth-overview) is strongly recommended. ## How Integrated API Keys Work (Conceptually) ### Install-Scoped Access * Each key is generated **per customer installation** * The key is bound to that customer + integration context and **cannot be reused across other customers** * Keys are generated **only in approved flows via the Pleo Web App** ### Pre-Scoped Permissions * Permissions/scopes are **configured by Pleo during integration setup** * The key can only perform operations allowed by these scopes * Scope management is **internal to Pleo**, not editable by the integration ### Integration Validation * Integrations must validate the key by making a **test API call** * Upon successful validation, the integration stores the key securely and tracks the relevant `company_id` or other Pleo identifiers * Integrations should support **storing multiple keys**, one per customer installation ## High-Level Workflow ### 1. Onboarding prerequisites (Integration Developer → Pleo) 1. **Request access** to build an accounting/ERP integration 2. **Confirm eligibility** for Integrated API Keys with Pleo 3. **Provide Marketplace integration details** (name, branding, support contacts, features) 4. **Pleo configures the integration** (“auth client”) with pre-scoped permissions ### 2. Customer install flow (Customer + Pleo) 1. Customer initiates installation via Pleo Marketplace or Accounting settings 2. Pleo presents an **Integrated API Key** step in the install modal 3. Pleo verifies the customer has the required permissions 4. If permitted, Pleo generates a **customer-specific key** and presents it to the customer ### 3. Customer transfers key to integration (Customer + Integration) 1. Customer copies the generated key 2. Integration provides a **secure input field** to paste and save the key 3. Integration must support **masking, secure storage, and future rotation per customer** ### 4. Integration validates and stores key (Integration + Pleo APIs) 1. Validate key with a test API call 2. On success: * Save key securely * Store relevant identifiers (company\_id) * Show “Connected” 3. On failure: * Show clear error * Prompt for re-entry or support contact ### 5. Ongoing maintenance * Customers may rotate or recreate keys * Integration must support **key updates, re-validation, and rotation per customer installation** ## Implementation Checklist for External Developers **Integration developer must implement:** * Connect screen with: * Secret API key input * Save + Test connection button * Clear error states * Secure key storage and masking * Key rotation / reconnect flow per customer * Minimal health check API call for validation **Pleo provides:** * Key generation UI in install flow * Scoped key permissions * Record visibility under **Settings → API Keys** after install ## Security Responsibilities (High-Level) * Treat Integrated API Keys as **secrets** * Mask keys after save; avoid logs, analytics, or client-side exposure * Rotate or replace compromised keys * Validate that keys have the required scopes * Manage keys **per customer installation** ## Integrated API Keys vs OAuth 2.0 | | **Integrated API Keys** | **OAuth 2.0** | | -------------------------- | --------------------------------------------------------------- | ---------------------------- | | Availability | Restricted / approved integrations only | Available | | Access model | Company-scoped (per-customer installation) | User-delegated | | Typical usage | Accounting / ERP multi-customer integrations | Multi-customer integrations | | Customer consent | Implicit in install | Explicit consent required | | Multi-customer support | Yes — one integration can serve multiple customer installations | Yes | | Authentication | Static per-customer Integrated API key | Access tokens | | Recommended for production | Approved exceptions | Default for all integrations | ## Typical Development Workflow 1. Onboard with Pleo and confirm Integrated API Key eligibility 2. Implement secure connect screen with key input 3. Validate key with a test API call 4. Support reconnect / rotation flows **per customer** 5. Optional: implement health check or minimal API calls to verify integration functionality Implementation details for installation, activation, key updates, and error handling are covered in: * [**Integration Design for Integrated API Keys**](/docs/current/integration-design/auth/integrated-api-keys/integration-design-for-integrated-api-keys) * [**User Experience Guidelines for Integrated API Keys**](/docs/current/integration-design/auth/integrated-api-keys/integration-design-user-exp-guidelines-for-integrated-api-keys) *** ## What Comes Next? * [**Integration Design for Integrated API Keys**](/docs/current/integration-design/auth/integrated-api-keys/integration-design-for-integrated-api-keys) *** ## Related Reading * [**User Experience Guidelines for Integrated API Keys**](/docs/current/integration-design/auth/integrated-api-keys/integration-design-user-exp-guidelines-for-integrated-api-keys) * [Security and Credential Management for Integrated API Keys](/docs/current/integration-design/auth/integrated-api-keys/integration-design-security-for-integrated-api-keys) ***