Skip to main content
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.
  • 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.
  • 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 AspectOAuth 2.0Integrated API Keys
User actionLogin & consentPaste credential
OwnershipUser accountInstallation credential
RenewalAutomaticManual replacement
Failure recoveryReconnect loginReplace key
Session conceptYesNo
Design interfaces accordingly.

​
What Comes Next?