Skip to main content
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. Integrated API Keys require approval from Pleo. They are typically used only for accounting/ERP integrations where OAuth 2.0 is not feasible.

​
Concepts and Terminology

ConceptTermDescription
Company credentialIntegrated API KeyA secret key generated during installation of a Pleo-approved integration, scoped to a single customer installation. Each customer receives a unique key.
Integration configurationAuth client / Marketplace entryDefines the scopes and permissions pre-configured into the key by Pleo. Managed internally by Pleo; no OAuth 2.0 client lifecycle exists.
Permission boundaryScoped accessThe set of API actions the integration is allowed to perform. Pre-configured at install time.
Company identityCompany_idIdentifies 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 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 KeysOAuth 2.0
AvailabilityRestricted / approved integrations onlyAvailable
Access modelCompany-scoped (per-customer installation)User-delegated
Typical usageAccounting / ERP multi-customer integrationsMulti-customer integrations
Customer consentImplicit in installExplicit consent required
Multi-customer supportYes — one integration can serve multiple customer installationsYes
AuthenticationStatic per-customer Integrated API keyAccess tokens
Recommended for productionApproved exceptionsDefault 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:

​
What Comes Next?