OAuth permissions and user roles

Understand which user roles can grant OAuth consent and how role changes affect existing connections

OAuth permissions in Airwallex determine which users can authorize third-party applications to access account data and perform operations. Understanding these permissions is important when building integrations, as role-based access controls directly impact connection stability and the authorization process.

OAuth authorization requires specific user roles to ensure proper access control and account security. Users with administrative or financial management privileges can grant OAuth consent to third-party applications.

Authorization roles

The following user roles can authorize OAuth connections:

Owner: Full account access and administration rights
Admin: Administrative access to account settings and configurations
Finance Admin: Financial operations and connection management

These roles have the necessary permissions to make security-sensitive decisions like granting third-party application access. Finance Admin users can grant OAuth consent consistent with their ability to manage other connection types, such as outbound connections to accounting platforms like Xero and QuickBooks.

OAuth consents are tied to the specific user who granted authorization. This binding between user and consent creates dependencies that affect connection stability when user permissions change.

Why consents track the authorizing user

When a user authorizes an OAuth application, the system creates a consent record associated with that user's account and role. This design ensures:

Accountability: Each authorization has a clear owner responsible for granting access
Security auditing: Changes to user permissions can be traced to specific consent decisions
Access validation: The system can verify that authorized users still have appropriate permissions

During token operations (refresh, validation), Airwallex verifies that the consent remains valid and that the account still has active administrative oversight.

Token validation and permissions

When your application refreshes an access token, Airwallex performs several validation checks:

Token validity: Verifies the refresh token is active and not expired
Consent status: Confirms the OAuth consent has not been revoked
Account status: Ensures the connected account remains active
User permissions: Verifies the original consenting user still has Owner, Admin, or Finance Admin role

If any validation check fails, the token refresh fails and your application receives an invalid_grant error.

Impact of role changes on connections

Role changes for users who granted OAuth consent directly affect OAuth connections. Understanding these impacts helps you build resilient integrations and set appropriate expectations with users.

When OAuth consents become invalid

OAuth consents become invalid in two scenarios:

User loses administrative access: If the consenting user loses their Owner, Admin, or Finance Admin role, the OAuth consent becomes invalid immediately. Token refresh requests will fail with an invalid_grant error.
User leaves the organization: If the consenting user's account is deleted, the OAuth consent becomes invalid when the account is removed. Token refresh requests will fail with authentication errors.

In both cases, the connection stops working and must be re-established by a current administrator.

Restoring invalid connections

To restore the connection, a current Owner, Admin, or Finance Admin must:

Navigate to Settings > Connections in the Airwallex web app
Disconnect the affected third-party integration
Re-authorize the integration to grant new consent

Best practices for user transitions

Monitor for authentication failures in your integrations.
Document which user authorized each critical integration.
Plan OAuth connection updates as part of user offboarding procedures.
Consider re-establishing connections periodically as team composition changes.

Planning for role-based access

Understanding OAuth permission requirements and management capabilities helps you design more resilient integrations and set appropriate user expectations.

Design considerations

When building OAuth integrations:

Document role requirements clearly: Explain that Owner, Admin, or Finance Admin must complete authorization.
Handle authentication failures gracefully: Build user-friendly error messages and recovery flows.
Support re-authorization: Allow users to reconnect when necessary.
Monitor token refresh success: Track connection health across your user base.

User communication

Set expectations with your users:

Authorization requirements: Owner, Admin, or Finance Admin users can complete authorization.
Role changes: If the authorizing user loses their admin role or leaves the organization, the connection will fail and must be re-authorized.
Connection maintenance: Recommend documenting which user authorized each integration for future reference.

Monitoring and support

Implement monitoring to maintain connection health:

Track authentication error patterns to identify role-related issues early.
Alert on repeated token refresh failures for specific accounts.
Build dashboards showing connection health across your user base.
Provide clear re-authorization workflows for users when connections fail.