> ## 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 Standalone API Keys

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

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

## UX Principles

Standalone API Keys behave differently from OAuth 2.0 authentication.

Users are providing a **long-lived company credential**, not logging into a session.

Your interface should therefore prioritise:

* Clarity of ownership
* Explicit confirmation of company connection
* Safe credential handling
* Predictable recovery when authentication fails

## API Key Input Experience

Users must have a clear and secure way to provide their 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 grants company-level access
* 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 enters API Key
2. User clicks **Connect** or **Save**
3. System validates authentication
4. Installation/activation process runs
5. Company association is confirmed
6. Integration becomes active

Users should never be left unsure whether authentication succeeded.

## Company Confirmation

Because Standalone API Keys connect to a **single company**, users must be able to confirm the connected organisation.

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

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

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

Users must be able to replace an API Key when it expires or is rotated.

### 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 installation
4. Company association is confirmed again
5. Integration returns to active state

## Expiry and Failure Recovery

API Keys may stop working unexpectedly.

Your UI should help users recover quickly.

### Recommended Behaviour

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

Example messaging:

> “Your connection to Pleo has expired. 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       | Standalone API Keys |
| ---------------- | --------------- | ------------------- |
| User action      | Login & consent | Paste credential    |
| Ownership        | User account    | Company 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 Standalone API Keys](/docs/current/integration-design/auth/api-keys/integration-design-security-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)
* [OAuth 2.0 Overview](/docs/current/integration-design/auth/oauth/integration-design-auth-oauth-overview)

***