> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0 Quick Start

> Get started with OAuth 2.0 authorization in minutes

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

<Note>
  **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.
</Note>

<Warning>
  **User Consent is Required:** Just because your application receives authorization tokens does not mean you should access user data or modify their information without explicit user consent. OAuth provides the mechanism for user-initiated interactions—always respect the principle of least privilege and only access what users have explicitly authorized. See the [Consent Management Guide](/guides/consent/overview) for compliance requirements and implementation details.
</Warning>

## What You'll Need

Before starting, ensure you have:

<CardGroup cols={2}>
  <Card title="API Keys" icon="key">
    Your `x-client-key` (public) and `x-secret-key` (private) from your technical account manager
  </Card>

  <Card title="Redirect URI" icon="arrow-turn-down-left" href="/guides/oauth/security#redirect-uri-security">
    A whitelisted callback URL where users return after authentication. Must use HTTPS for production; HTTP only for development. Custom schemes require TAM approval.
  </Card>

  <Card title="HTTPS Endpoint" icon="lock">
    A secure endpoint to receive the authorization code (production only)
  </Card>

  <Card title="User Consent" icon="user-check" href="/guides/consent/overview">
    Explicit user permission to access their account and perform actions on their behalf. See [Consent Management](/guides/consent/overview) for compliance requirements.
  </Card>
</CardGroup>

### User Consent Requirements

Users must understand and explicitly consent to what your application will do with their authorization:

<CardGroup cols={2}>
  <Card title="Data Access" icon="database">
    * Wallet balance and transaction history
    * Account information and preferences
    * Card details and spending activity
  </Card>

  <Card title="Actions Permitted" icon="bolt">
    * Initiate transactions
    * Manage cards and wallets
    * Update account settings
  </Card>
</CardGroup>

**Example consent language:**

> "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

<Note>
  **Regulatory Compliance:** The Baanx API includes a comprehensive [Consent Management system](/guides/consent/overview) 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.
</Note>

<Warning>
  **Security First:** Never expose your `x-secret-key` in client-side code, mobile apps, or public repositories. Keep it server-side only.
</Warning>

## Choose Your Implementation

We support two OAuth flow implementations depending on your use case:

<CardGroup cols={2}>
  <Card title="API Mode Flow" icon="code" href="/guides/oauth/api-mode">
    **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

    **Best for:** Mobile apps, custom branded experiences, headless systems
  </Card>

  <Card title="Hosted UI Flow" icon="browser" href="/guides/oauth/hosted-ui">
    **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

    **Best for:** Web apps, SaaS integrations, third-party services
  </Card>
</CardGroup>

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

<Note>
  **Important:** The JWT token from OAuth initiation is NOT the same as your access token. Use access tokens for API requests.
</Note>

## 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)

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant API as API Gateway
    participant User as End User

    App->>API: 1. Initiate with mode=api (GET /authorize/initiate)
    API-->>App: JWT session token
    User->>App: 2. Enter credentials in your app
    App->>API: 3. Login user (POST /auth/login)
    API-->>App: Access token
    App->>API: 4. Generate auth code (POST /authorize)
    API-->>App: Authorization code
    App->>API: 5. Exchange code for tokens (POST /token)
    API-->>App: Access token + Refresh token
```

### Hosted UI Flow (4 Steps)

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant API as API Gateway
    participant UI as Hosted UI
    participant User as End User

    App->>API: 1. Initiate OAuth (GET /authorize/initiate)
    API-->>App: Hosted UI URL + session token
    App->>UI: 2. Redirect user to hosted UI
    User->>UI: Enter credentials
    UI->>API: 3. Authenticate & authorize (automatic)
    API-->>UI: Authorization code
    UI->>App: Redirect back with code
    App->>API: 4. Exchange code for tokens (POST /token)
    API-->>App: Access token + Refresh token
```

## Security Features

<CardGroup cols={2}>
  <Card title="PKCE Required" icon="shield-check">
    Code challenge/verifier prevents authorization code interception
  </Card>

  <Card title="State Parameter" icon="shield-halved">
    Random state string protects against CSRF attacks
  </Card>

  <Card title="Redirect URI Validation" icon="link" href="/guides/oauth/security#redirect-uri-security">
    Only whitelisted URIs accepted to prevent redirect attacks. Learn about HTTPS requirements, custom schemes, and CORS.
  </Card>

  <Card title="Short-lived Sessions" icon="clock">
    10-minute session expiry limits exposure window
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Choose Your Flow">
    Decide between [Hosted UI](/guides/oauth/hosted-ui) (recommended) or [API Mode](/guides/oauth/api-mode) based on your needs
  </Step>

  <Step title="Implement Authorization">
    Follow the step-by-step guide for your chosen flow
  </Step>

  <Step title="Manage Tokens">
    Learn about [token lifecycle and refresh](/guides/oauth/token-management)
  </Step>

  <Step title="Review Security">
    Read [security best practices](/guides/oauth/security) before going to production
  </Step>
</Steps>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Third-party Integration" icon="plug">
    Allow external applications to access your users' data with their permission. Use **Hosted UI** for simplicity and built-in security.
  </Accordion>

  <Accordion title="Mobile Application" icon="mobile">
    Build a native mobile app with custom branding. Use **API Mode** to control the entire user experience while maintaining security.
  </Accordion>

  <Accordion title="Single Sign-On (SSO)" icon="arrow-right-to-bracket">
    Enable users to log in across multiple applications with one set of credentials. **Hosted UI** works best for standard SSO implementations.
  </Accordion>

  <Accordion title="Microservices Architecture" icon="diagram-project">
    Allow your backend services to communicate securely on behalf of users. Use **API Mode** for service-to-service authentication.
  </Accordion>
</AccordionGroup>

## Quick Links

<CardGroup cols={3}>
  <Card title="Hosted UI Guide" icon="browser" href="/guides/oauth/hosted-ui">
    Complete implementation guide
  </Card>

  <Card title="API Mode Guide" icon="code" href="/guides/oauth/api-mode">
    Custom flow implementation
  </Card>

  <Card title="Token Management" icon="rotate" href="/guides/oauth/token-management">
    Token lifecycle & refresh
  </Card>

  <Card title="Security Guide" icon="shield" href="/guides/oauth/security">
    Best practices & pitfalls
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Detailed endpoint docs
  </Card>

  <Card title="Troubleshooting" icon="screwdriver-wrench" href="/guides/oauth/troubleshooting">
    Common issues & solutions
  </Card>
</CardGroup>

## Need Help?

<Card title="Get Support" icon="headset">
  Having trouble with OAuth implementation? Check our [troubleshooting guide](/guides/oauth/troubleshooting) or contact our support team.
</Card>