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

# Security and Credential Management for Integrated API Keys

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

### Recommended Storage Options

* 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

### Recommended Monitoring

* 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?

* [Integrated API Key Customer Installation Flow](/docs/current/integration-design/auth/integrated-api-keys/integration-design-integrated-api-key-user-install-flow)

***

## Related Reading

* [Integrated API Keys Overview](/docs/current/authentication/integrated-api-keys-overview)
* [User Experience Guidelines for Integrated API Keys](/docs/current/integration-design/auth/integrated-api-keys/integration-design-user-exp-guidelines-for-integrated-api-keys)
* [OAuth 2.0 Overview](/docs/current/authentication/oauth/oauth-overview)

***