Skip to main content

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.

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?