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
- User enters API Key
- User clicks Connect or Save
- System validates authentication
- Installation/activation process runs
- Company association is confirmed
- Integration becomes active
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
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.”
- 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
••••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
- User selects Update API Key
- User enters new key
- System revalidates installation
- Company association is confirmed again
- 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
“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
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 |