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

# Integration Design for Integrated API Keys

This article describes **integration architecture, lifecycle behaviour, and UX expectations** when building integrations that use **Integrated API Keys**.

If you are unfamiliar with Integrated API Keys, start with the [**Integrated API Keys Overview**](/docs/current/authentication/integrated-api-keys-overview), which explains availability, intended usage, and conceptual behaviour.

This document focuses on **how integrations must behave technically** and securely when using Integrated API Keys.

## Integration Model

Integrated API Keys enforce a **1-to-1 integration model**:

```text theme={null}
One system ←→ One Pleo company (per install)
```

The same principle applies if you have a [**multi-entity**](/docs/current/integration-design/auth/multi-entity/integration-design-auth-multi-entity-overview) setup.

## Integration Model Assumptions

Integrated API Keys are **per-customer (per installation)**:

* The **integration itself is multi-customer** (one integration can be installed by many customers)
* Each customer installation gets a **unique key generated by Pleo**, scoped to that installation
* Integrations must store **one key per customer tenant** and support rotation/reconnect per customer
* No delegated user authorisation within the integration context
* Key generation and permissions are controlled by Pleo

## Design Implication

Treat each Integrated API Key as a **company-level installation credential** for a **specific customer**, not a user login or session.\
Your integration must manage **key storage, validation, and rotation per customer**.

## Authentication Responsibilities

When using Integrated API Keys, your integration is responsible for:

* Receiving the key from the customer (generated by Pleo during install)
* Validating API connectivity
* Persisting the integration context (`company_id` or other identifiers) **per customer**
* Maintaining the key lifecycle state (reconnect, update, rotate) for each customer

Pleo handles **key generation, pre-scoping, and association with the customer install**, but does **not** manage storage, validation, or reconnect logic. Your integration must implement these steps.

## Installation and Activation Requirements

After the customer provides the Pleo-generated Integrated API Key, the integration must complete an **activation process** to verify connectivity.

### Required Activation Behaviour

Integrations **must**:

* Call a test API endpoint to validate the key
* Confirm that the key is valid and linked to the correct `company_id`
* Store the `company_id` and key securely for future requests
* Prevent the integration from becoming active if validation fails

This ensures the integration is correctly associated with the intended Pleo customer.

### Error Handling Expectations

If activation fails:

* Prevent the integration from entering an active state
* Display actionable error messaging
* Allow the customer to re-enter the key and retry activation

## Company ID Handling

The `company_id` links an Integrated API Key to the correct customer.

### Required Integration Behaviour

Integrations **must**:

* Persist the `company_id` obtained during validation
* Use the correct `company_id` in all subsequent API requests
* Ensure requests are always scoped to the associated customer

### Validation Expectations

Integrations should prevent:

* Using a key with the wrong `company_id`
* Sending requests without proper customer scoping
* Silent connection to a different customer after key replacement

## Permission and Scope Awareness

Integrated API Keys are created with **pre-configured scopes per customer installation**.

Integrations should:

* Validate required scopes during activation
* Surface clear errors if permissions are insufficient
* Avoid assuming full API access

> Pre-scoped permissions reduce risk and simplify integration logic.

## Key Updates and Re-Authentication

Customers may rotate or replace Integrated API Keys via the Pleo Web App.

### Required Integration Behaviour

Integrations **must**:

* Allow entry of a new key to replace the previous credential **for that customer**
* Repeat validation and company association after key replacement
* Confirm required API scopes are present
* Prevent activation if validation fails

### Expected System Behaviour

After a key update:

1. Invalidate previous authentication state for that customer
2. Validate the new key
3. Confirm or update the associated `company_id`
4. Resume normal operation only after successful validation

## Failure and Expiry Handling

Keys may become invalid if they:

* Are rotated or replaced
* Lose required permissions
* Are revoked

Integrations should:

* Detect authentication failures per customer
* Notify users clearly
* Allow immediate replacement and revalidation

## Security Responsibilities

Integrated API Keys are **static, company-level credentials per customer installation**.

Integrations **must**:

* Store keys securely and encrypted at rest
* Mask keys in the UI; avoid logs or analytics exposure
* Rotate or replace compromised keys
* Validate that keys have the required scopes
* Use keys only for the intended customer context

## User Interface / UX Expectations

* Provide a dedicated **secure input field** for the Pleo-generated key
* Mask the key after entry
* Show the connected `company_id` clearly
* Validate the key immediately and confirm connection
* Support **Update / Reconnect flows** for rotated keys
* Provide actionable, non-technical error messaging

## Integrated API Keys vs OAuth 2.0

| UX / Integration Aspect    | Integrated API Keys                               | OAuth 2.0                    |
| -------------------------- | ------------------------------------------------- | ---------------------------- |
| Availability               | Restricted / approved integrations only           | Available                    |
| Access model               | Company-scoped per customer                       | User-delegated               |
| Typical usage              | Accounting / ERP single-company per install       | Multi-customer integrations  |
| Customer consent           | Implicit in install                               | Explicit consent required    |
| Multi-customer support     | Yes — one integration, multiple customer installs | Yes                          |
| Authentication             | Static pre-scoped key                             | Access tokens                |
| Recommended for production | Approved exceptions                               | Default for all integrations |

## Typical Development Workflow (Conceptual)

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 for each customer
4. Support reconnect / key rotation flows per customer
5. Optional: implement health checks for integration functionality

***

## What Comes Next?

* [User Experience Guidelines for Integrated API Keys](/docs/current/integration-design/auth/integrated-api-keys/integration-design-user-exp-guidelines-for-integrated-api-keys)

***

## Related Reading

* [Integrated API Keys Overview](/docs/current/authentication/integrated-api-keys-overview)
* [Security and Credential Management for Integrated API Keys](/docs/current/integration-design/auth/integrated-api-keys/integration-design-security-for-integrated-api-keys)
* [Integrated API Key Customer Installation Flow](/docs/current/integration-design/auth/integrated-api-keys/integration-design-integrated-api-key-user-install-flow)
* [OAuth 2.0 Overview](/docs/current/authentication/oauth/oauth-overview)

***