Skip to main content
This article describes integration architecture and lifecycle behaviour when building integrations that use Standalone API Keys. If you are unfamiliar with Standalone API Keys, start with the Standalone API Keys Overview, which explains availability, intended usage, and conceptual behaviour. This document focuses on how integrations must behave technically when using API Keys.

​
Integration Model

Standalone API Keys enforce a 1-to-1 integration model: 
One system ←→ One Pleo company
The same principle applies if you have a multi-entity setup.

​
Integration Model Assumptions

Your integration must assume:
  • No multi-customer onboarding
  • No delegated user authorisation
  • No tenant switching
  • No shared credentials

​
Design Implication

Treat the API Key as a company-level installation, not a user login or session.

​
Authentication Responsibilities

When using Standalone API Keys, your integration is responsible for managing authentication behaviour. Your system must:
  • Receive the API Key from the user
  • Validate API connectivity
  • Associate the integration with a single company
  • Maintain authentication lifecycle state
Pleo does not manage the key’s lifecycle or credential rotation for API Key integrations.

​
Installation and Activation Requirements

After a user provides a valid Standalone API Key, the integration must complete an activation process to verify connectivity and establish company association.

​
Required Activation Behaviour

Integrations must:
  • Call the Installation endpoint after a key is provided
  • Validate that authentication succeeds
  • Extract the associated company_id from the API response
  • Persist the company_id for future requests
  • Prevent the integration from entering an active state if activation fails
The activation step confirms that the API Key is valid and that the integration is connected to the intended Pleo organisation.

​
Error Handling Expectations

If activation fails, integrations should:
  • Prevent the integration from entering an active state
  • Display actionable error messaging
  • Allow the user to replace the API Key and retry activation

​
Company ID Handling

The company_id links a Standalone API Key to the correct Pleo organisation and is required for most API requests. The Company ID establishes the organisational boundary of the integration and must be treated as part of the authentication context.

​
Required Integration Behaviour

Integrations must:
  • Persist the company_id obtained during activation
  • Use the correct company_id in all subsequent API requests where required
  • Ensure requests are always scoped to the associated company

​
Validation Expectations

Integrations should prevent situations where:
  • An API Key is used with an incorrect company_id
  • Requests are sent without organisational scoping
  • A replaced API Key silently connects to a different company without confirmation
Incorrect company scoping may result in rejected API calls or unintended data access boundaries.

​
Permission and Scope Awareness

Standalone API Keys are created with predefined API scopes. Integrations should:
  • Validate required permissions during setup
  • Surface clear errors if permissions are insufficient
  • Avoid assuming full API access
Design integrations to fail clearly when required scopes are missing.

​
API Key Updates and Re-Authentication

Users must be able to update their Standalone API Key to maintain integration access. Because API Keys may expire, be revoked, or rotated, integrations must support key replacement and revalidation.

​
Required Integration Behaviour

Integrations must:
  • Allow a new API Key to replace the previous credential
  • Repeat the installation and activation process after a new key is provided
  • Revalidate company association using the Installation endpoint
  • Verify that the new API Key contains the required API scopes
  • Prevent the integration from becoming active if validation fails

​
Expected System Behaviour

After a key update:
  1. The previous authentication state must be invalidated
  2. The new API Key must be validated
  3. The associated company_id must be confirmed or updated
  4. Normal integration operation resumes only after successful validation

​
Failure and Expiry Handling

API Keys may become invalid if they:
  • Expire
  • Are revoked
  • Are replaced
  • Lose permissions
Integrations should:
  • Detect authentication failures
  • Notify users clearly
  • Request a replacement key when required

​
Relationship to OAuth 2.0

Standalone API Keys shift responsibility from platform-managed authentication to integration-managed lifecycle control.
ResponsibilityOAuth 2.0Standalone API Keys
Token/Key lifecycleManaged by PleoManaged by integration
User consentRequiredNot applicable
Credential rotationAutomaticManual
Multi-company supportYesNo
Authentication typeAccess tokensStatic API key

​
What Comes Next?