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

# User Experience Guidelines for Integrated API Keys

This article defines **user experience (UX) expectations** for integrations that use **Integrated API Keys**.

It focuses on **how users interact with Integrated API Key authentication** inside your product.

## UX Principles

Integrated API Keys behave differently from OAuth 2.0 authentication.

Users are providing a **customer-specific installation credential**, not logging into a session.

Your interface should therefore prioritise:

* Clear guidance on where the key comes from
* Safe credential handling
* Explicit confirmation of company connection
* Predictable recovery when authentication fails

## API Key Input Experience

Users must have a clear and secure way to provide their Integrated API Key.

### Required Behaviour

Your UI must:

* Provide a dedicated API Key input field
* Clearly label the field as a **secret credential**
* Accept secure paste input
* Mask the API Key during entry where possible
* Never display the full key after saving

### Recommended Guidance Text

Explain to users that:

* The API Key was **generated by Pleo during the installation process**
* The key grants **company-level access to the integration**
* The key should be stored securely
* The key cannot be viewed again after saving

## Saving and Confirmation Behaviour

After a user submits an API Key, the system should immediately validate it.

### Expected UX Flow

1. User copies the Integrated API Key from Pleo
2. User enters the API Key into the integration
3. User clicks **Connect** or **Save**
4. System validates authentication
5. Company association is confirmed
6. Integration becomes active

Users should never be left unsure whether authentication succeeded.

## Company Confirmation

Integrated API Keys are **linked to a specific Pleo company installation**.

Users should be able to confirm the organisation associated with the connection.

### Required Behaviour

Your UI must:

* Display the associated `company_id` after activation
* Clearly indicate which company is connected
* Confirm successful installation visually

### Example Confirmation Signals

* “Connected to Company ID: XXXXX”
* Success status indicator
* Connected state badge

This prevents accidental connections to the wrong organisation.

## Error Handling Experience

Authentication failures must be clearly communicated.

### Errors Should:

* Explain what failed
* Avoid technical jargon where possible
* Provide a clear recovery action

### Examples

Good:

* “The API Key appears to be invalid. Please check and try again.”
* “This key does not have the required permissions.”

Avoid:

* Generic messages such as “Authentication failed.”

### Required Behaviour

If activation fails:

* The integration must not enter an active state
* Users must be able to retry immediately
* The API Key field must remain editable

## API Key Visibility Rules

Integrated API Keys must be treated as sensitive secrets within the interface.

### Required UX Behaviour

* Mask the API Key after saving
* Never allow full key retrieval
* Do not expose keys in logs or UI messages
* Avoid displaying partial keys unless necessary for identification

If identification is needed, show only minimal characters (for example: `••••abcd`).

## Updating API Keys

Customers may rotate or replace Integrated API Keys.

Users must be able to replace an API Key when required.

### Required UX Behaviour

Your interface must:

* Provide an **Update API Key** or **Reconnect** action
* Allow entry of a replacement key
* Re-run validation automatically
* Clearly show reconnection progress

### Expected User Flow

1. User selects **Update API Key**
2. User enters new key
3. System revalidates authentication
4. Company association is confirmed again
5. Integration returns to active state

## Expiry and Failure Recovery

Integrated API Keys may stop working if they are **revoked, rotated, or lose permissions**.

Your UI should help users recover quickly.

### Recommended Behaviour

* Detect authentication failures automatically
* Display persistent connection warnings
* Provide a clear **Replace API Key** or **Reconnect** action
* Avoid silent failures

Example messaging:

> “Your connection to Pleo has been interrupted. Please update your API Key to restore access.”

## Status and Connection Visibility

Users should always understand the current integration state.

### Recommended Connection States

* Connected
* Validation in progress
* Connection failed
* Action required

Avoid ambiguous states where users cannot determine whether the integration is functioning.

## Relationship to OAuth 2.0 UX

OAuth 2.0 and API Keys create different mental models for users.

| UX Aspect        | OAuth 2.0       | Integrated API Keys     |
| ---------------- | --------------- | ----------------------- |
| User action      | Login & consent | Paste credential        |
| Ownership        | User account    | Installation credential |
| Renewal          | Automatic       | Manual replacement      |
| Failure recovery | Reconnect login | Replace key             |
| Session concept  | Yes             | No                      |

Design interfaces accordingly.

***

## What Comes Next?

* [Security and Credential Management for Integrated API Keys](/docs/current/integration-design/auth/integrated-api-keys/integration-design-security-for-integrated-api-keys)

***

## Related Reading

* [Integrated API Keys Overview](/docs/current/authentication/integrated-api-keys-overview)
* [Integrated API Key Customer Installation Flow](/docs/current/integration-design/auth/integrated-api-keys/integration-design-integrated-api-key-user-install-flow)
* [OAuth 2.0 Overview](/docs/current/authentication/oauth/oauth-overview)

***