Overview
OAuth 2.0 allows your application to obtain authorization so that users can interact with their accounts through your application without providing their credentials directly to your backend. This API implements OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange), providing enhanced security for both web and mobile applications.Why OAuth 2.0? OAuth enables users to grant your application permission to act on their behalf without sharing their password. This authorization model ensures users maintain control over their data and can revoke access at any time. PKCE adds an extra layer of security to prevent authorization code interception attacks.
What You’ll Need
Before starting, ensure you have:API Keys
Your
x-client-key (public) and x-secret-key (private) from your technical account managerRedirect URI
A whitelisted callback URL where users return after authentication. Must use HTTPS for production; HTTP only for development. Custom schemes require TAM approval.
HTTPS Endpoint
A secure endpoint to receive the authorization code (production only)
User Consent
Explicit user permission to access their account and perform actions on their behalf. See Consent Management for compliance requirements.
User Consent Requirements
Users must understand and explicitly consent to what your application will do with their authorization:Data Access
- Wallet balance and transaction history
- Account information and preferences
- Card details and spending activity
Actions Permitted
- Initiate transactions
- Manage cards and wallets
- Update account settings
“By connecting your account, you authorize [Your App Name] to view your wallet balance, transaction history, and initiate transactions on your behalf. You can revoke access at any time from your account settings.”Best practices:
- Obtain consent during first login or feature access
- Use clear, non-technical language
- Provide a way for users to review and revoke permissions
- Only request access to data your application actually needs
Regulatory Compliance: The Baanx API includes a comprehensive Consent Management system to help you meet GDPR, CCPA, and E-Sign Act requirements. During user registration and authorization flows, you’ll need to collect and track user consent for marketing communications, data access, and terms of service. The system maintains an immutable audit trail for all consent changes.
Choose Your Implementation
We support two OAuth flow implementations depending on your use case:API Mode Flow
For custom authentication experiences
- Full control over the login UI
- Handle user credentials directly
- Custom branding and flow
- More integration steps (5 steps)
- Requires additional security measures
Hosted UI Flow
Recommended for most applications
- Users authenticate on our secure hosted login page
- No need to handle credentials in your app
- Built-in security and compliance
- Faster implementation (4 steps)
- Perfect for web applications
Token Types Explained
The API uses three different token types for different purposes:| Token Type | Purpose | Lifetime | Usage |
|---|---|---|---|
| JWT Token | OAuth flow session | 10 minutes | Only used during OAuth flow initialization |
| Access Token | API authentication | 6 hours | Include in Authorization: Bearer header for all API calls |
| Refresh Token | Token renewal | 7 days | Exchange for new access tokens when they expire |
Important: The JWT token from OAuth initiation is NOT the same as your access token. Use access tokens for API requests.
Quick Comparison
| Feature | Hosted UI | API Mode |
|---|---|---|
| Implementation Steps | 4 | 5 |
| Login Page | Hosted by us | Custom (your app) |
| Security Complexity | Lower | Higher |
| Setup Time | ~30 minutes | ~2 hours |
| User Experience | Standard | Fully custom |
| Credential Handling | We handle it | You handle it |
| Baanx Configuration | Required (Hosted UI setup) | Standard setup only |
| Best For | Web apps | Mobile apps |
Flow Overview
API Mode Flow (5 Steps)
Hosted UI Flow (4 Steps)
Security Features
PKCE Required
Code challenge/verifier prevents authorization code interception
State Parameter
Random state string protects against CSRF attacks
Redirect URI Validation
Only whitelisted URIs accepted to prevent redirect attacks. Learn about HTTPS requirements, custom schemes, and CORS.
Short-lived Sessions
10-minute session expiry limits exposure window
Next Steps
Manage Tokens
Learn about token lifecycle and refresh
Review Security
Read security best practices before going to production
Common Use Cases
Third-party Integration
Third-party Integration
Allow external applications to access your users’ data with their permission. Use Hosted UI for simplicity and built-in security.
Mobile Application
Mobile Application
Build a native mobile app with custom branding. Use API Mode to control the entire user experience while maintaining security.
Single Sign-On (SSO)
Single Sign-On (SSO)
Enable users to log in across multiple applications with one set of credentials. Hosted UI works best for standard SSO implementations.
Microservices Architecture
Microservices Architecture
Allow your backend services to communicate securely on behalf of users. Use API Mode for service-to-service authentication.
Quick Links
Hosted UI Guide
Complete implementation guide
API Mode Guide
Custom flow implementation
Token Management
Token lifecycle & refresh
Security Guide
Best practices & pitfalls
API Reference
Detailed endpoint docs
Troubleshooting
Common issues & solutions
Need Help?
Get Support
Having trouble with OAuth implementation? Check our troubleshooting guide or contact our support team.