Skip to main content
This article defines security and credential management expectations when working with Integrated API Keys. It focuses on how integrations must protect customer-specific credentials, manage lifecycle events, and maintain secure operation across multiple installations. Integrated API Keys are static, pre-scoped company credentials generated by Pleo during an approved integration install flow. Each customer installation produces its own unique key, and integrations are responsible for securely managing those credentials.

​
Security Ownership Model

Security responsibilities are shared between Pleo and the integration developer.

​
Pleo Responsibilities

Pleo manages:
  • Key generation during installation
  • Permission scoping
  • Association between key, integration, and company
  • Key visibility within the Pleo Web App

​
Integration Responsibilities

Your integration is responsible for:
  • Receiving the key securely from the customer
  • Validating API connectivity
  • Secure storage and protection
  • Managing credential lifecycle events
  • Handling reconnection and key replacement
Pleo does not manage how keys are stored or rotated inside your system.

​
Key Security Principles

Integrated API Keys must be treated as high-sensitivity secrets.

​
Core Principles

  • Treat keys like passwords or private tokens
  • Store keys only on trusted backend systems
  • Apply least-privilege thinking even with pre-scoped permissions
  • Prevent exposure through logs, analytics, or client-side code
  • Isolate credentials per customer tenant
Because integrations are multi-customer, a compromise must never expose access to other tenants.

​
Secure Storage Requirements

Each Integrated API Key represents access to one customer company and must be stored securely.

​
Required Practices

Integrations must:
  • Store keys encrypted at rest
  • Persist keys only in backend systems
  • Mask keys after initial entry
  • Prevent retrieval of full keys after saving
  • Segregate credentials per customer tenant
Keys must never be embedded in:
  • Frontend applications
  • Mobile apps
  • Browser storage
  • Client-side JavaScript
  • Managed secrets vaults (AWS Secrets Manager, HashiCorp Vault)
  • Encrypted environment variables
  • Secure server-side credential stores

​
Transmission and Handling

When transmitting or processing Integrated API Keys:
  • Always use HTTPS
  • Send keys using headers, not query parameters
  • Avoid temporary storage in logs or debug output
  • Validate format before submission where possible
Keys should only ever pass through secure backend channels.

​
Multi-Customer Credential Isolation

Integrated API Keys are per installation, meaning your integration will store multiple keys. Your system must ensure:
  • Each key maps to exactly one customer tenant
  • Keys are never shared across customers
  • Requests always use the correct associated company_id
  • Credential access is scoped internally by tenant context
Failure to isolate credentials may result in cross-company data exposure.

​
Permission and Scope Awareness

Integrated API Keys are created with pre-configured scopes defined by Pleo. Integrations should:
  • Verify required permissions during activation
  • Surface clear errors if permissions are insufficient
  • Avoid assuming unrestricted API access
Pre-scoped permissions simplify implementation but do not remove security responsibility.

​
Key Rotation and Replacement

Customers may rotate or recreate Integrated API Keys within the Pleo Web App. Integrations must support secure replacement.

​
Required Workflow

  1. Customer generates a replacement key in Pleo
  2. User updates the key inside the integration
  3. Integration revalidates API connectivity
  4. Associated company_id is confirmed
  5. Previous credential is invalidated internally
Automated monitoring for authentication failures is strongly recommended.

​
Compromise and Incident Response

If a key is suspected to be exposed: Integrations must:
  • Immediately disable affected authentication
  • Prompt the user to replace the key
  • Revalidate the new credential
  • Review logs for suspicious activity
Because keys are tenant-scoped, incident handling should remain isolated to the affected customer.

​
Logging and Monitoring

Logging must balance observability with credential protection.

​
Required Behaviour

  • Never log full API Keys
  • Mask sensitive values
  • Store only minimal identifiers if required (e.g. last 4 characters)
  • Monitor authentication failures and permission errors
  • Detect repeated authentication failures
  • Alert users when reconnection is required
  • Surface degraded integration states clearly

​
Lifecycle Expectations

Integrated API Keys may become invalid if they:
  • Are rotated or replaced
  • Are revoked
  • Lose required permissions
  • Become disconnected during configuration changes
Integrations should detect failures quickly and guide users toward recovery.

​
Summary

Integrated API Keys introduce a shared security model:
  • Pleo manages generation and permission scoping
  • Integrations manage storage, lifecycle, and operational security
  • Each customer installation requires independent credential handling
Following secure storage, tenant isolation, and lifecycle management practices ensures integrations remain safe, predictable, and scalable across multiple customers.

​
What Comes Next?