Skip to main content
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, 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: 
One system ←→ One Pleo company (per install)
The same principle applies if you have a multi-entity 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 AspectIntegrated API KeysOAuth 2.0
AvailabilityRestricted / approved integrations onlyAvailable
Access modelCompany-scoped per customerUser-delegated
Typical usageAccounting / ERP single-company per installMulti-customer integrations
Customer consentImplicit in installExplicit consent required
Multi-customer supportYes — one integration, multiple customer installsYes
AuthenticationStatic pre-scoped keyAccess tokens
Recommended for productionApproved exceptionsDefault 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?