> ## 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 WarningCallout = ({title, children, icon = "⚠️"}) => <div style={{
  backgroundColor: 'var(--recommended-bg)',
  borderLeft: '4px solid hsl(34, 91%, 60%)',
  borderRadius: '10px',
  padding: '18px 22px',
  marginBottom: '20px',
  boxShadow: '1px 1px 3px hsl(34, 91%, 60%)'
}}>
    <div style={{
  display: 'flex',
  alignItems: 'flex-start',
  gap: '14px'
}}>
      <span style={{
  fontSize: '22px',
  lineHeight: '1',
  flexShrink: 0
}}>
        {icon}
      </span>
      <div>
        {title && <div style={{
  fontSize: '16px',
  fontWeight: 600,
  color: 'var(--recommended-title)',
  marginBottom: '6px'
}}>
            {title}
          </div>}
        <div style={{
  fontSize: '14px',
  lineHeight: 1.65
}}>
          {children}
        </div>
      </div>
    </div>
  </div>;

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.

<WarningCallout title="Availability Notice">
  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
</WarningCallout>

## 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**

```mermaid theme={null}
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
    style A2 white-space:normal
    style B1 white-space:normal
    style B2 white-space:normal
    style B3 white-space:normal
    style C1 white-space:normal
    style C2 white-space:normal
    style C3 white-space:normal
    style D1 white-space:normal
    style D3 white-space:normal
    style D4 white-space:normal
    style D5 white-space:normal
    style D6 white-space:normal

    %% Make subgraphs transparent with black borders
    style Dev fill:none,stroke:#000000
    style Pleo fill:none,stroke:#000000
    style Customer fill:none,stroke:#000000
    style Integration fill:none,stroke:#000000

    %% Connections across roles
    A2 --> B1
    C1 --> B3
    B3 --> C2
    C3 --> D1



```

## 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)

***