> ## 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.

# Integration Design for Standalone API Keys

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**](/docs/current/authentication/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**:

```html theme={null}
One system ←→ One Pleo company
```

The same principle applies if you have a [**multi-entity**](/docs/current/integration-design/auth/multi-entity/integration-design-auth-multi-entity-overview) 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**](/reference/installations/get-client-installation) 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**](/docs/current/authentication/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**.

| Responsibility        | OAuth 2.0       | Standalone API Keys    |
| --------------------- | --------------- | ---------------------- |
| Token/Key lifecycle   | Managed by Pleo | Managed by integration |
| User consent          | Required        | Not applicable         |
| Credential rotation   | Automatic       | Manual                 |
| Multi-company support | Yes             | No                     |
| Authentication type   | Access tokens   | Static API key         |

***

## What Comes Next?

* [User Experience Guidelines for Standalone API Keys](/docs/current/integration-design/auth/api-keys/integration-design-user-exp-guidelines-for-standalone-api-keys)

***

## Related Reading

* [Standalone API Keys Overview](/docs/current/authentication/standalone-api-keys-overview)
* [Standalone API Key Workflow Guide](/docs/current/guides/standalone-api-keys-workflow-guide)
* [User Experience Guidelines for Standalone API Keys](/docs/current/integration-design/auth/api-keys/integration-design-user-exp-guidelines-for-standalone-api-keys)
* [Security and Credential Management for Standalone API Keys](/docs/current/integration-design/auth/api-keys/integration-design-security-for-standalone-api-keys)
* [OAuth 2.0 Overview](/docs/current/integration-design/auth/oauth/integration-design-auth-oauth-overview)

***