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

# API Reference

> Complete API reference for the Baanx multi-tenant gateway

## Welcome to the Baanx API

The Baanx API is a comprehensive multi-tenant gateway that enables financial applications with OAuth 2.0 authentication, card management, cryptocurrency wallet operations, and blockchain delegation capabilities.

This API reference provides detailed documentation for all endpoints, including request/response schemas, authentication requirements, and practical examples.

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/guides/oauth/quickstart">
    Learn how to authenticate and make your first API call
  </Card>

  <Card title="OpenAPI Specification" icon="file-code" href="/api-reference/openapi.json">
    Download the complete OpenAPI 3.1 specification
  </Card>

  <Card title="Guides" icon="book" href="/guides/oauth/quickstart">
    Step-by-step integration guides for common workflows
  </Card>

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

## Core Capabilities

<AccordionGroup>
  <Accordion title="OAuth 2.0 & Authentication" icon="shield-check">
    Secure authorization flow with PKCE support, enabling third-party applications to access user accounts safely. Supports both hosted UI and custom authentication modes.

    **Key Features:**

    * Authorization Code Flow with PKCE
    * Hosted UI for simplified integration
    * API mode for custom authentication UX
    * Refresh token support (184-day expiry)
    * Session management and token revocation
  </Accordion>

  <Accordion title="User Management" icon="user">
    Complete user lifecycle management including registration, verification, profile management, and settings.

    **Key Features:**

    * Multi-step registration with email/phone verification
    * KYC and identity verification
    * Profile and settings management
    * Secure credential handling
  </Accordion>

  <Accordion title="Card Operations" icon="credit-card">
    Manage physical and virtual debit cards linked to cryptocurrency wallets.

    **Key Features:**

    * View card details securely (one-time tokens)
    * PIN management (view and set)
    * Card activation and status control
    * Transaction history and limits
  </Accordion>

  <Accordion title="Wallet Management" icon="wallet">
    Support for both custodial (platform-managed) and non-custodial (user-controlled) wallet models.

    **Custodial Features:**

    * Platform-managed keys and security
    * Direct card linking
    * Whitelist-based withdrawals
    * Multi-currency support

    **Non-Custodial Features:**

    * External wallet registration
    * User maintains custody
    * Priority management for multiple wallets
    * Real-time balance and allowance tracking
  </Accordion>

  <Accordion title="Blockchain Delegation" icon="link">
    Enable non-custodial users to grant spending authority for card payments while maintaining full custody of assets.

    **Key Features:**

    * EVM chain support (Linea, Ethereum)
    * Solana support
    * On-chain transaction verification
    * Signature-based proof of ownership
    * Flexible allowance management
  </Accordion>

  <Accordion title="Consent Management" icon="clipboard-check">
    Comprehensive consent tracking system for regulatory compliance with GDPR, CCPA, and E-Sign Act requirements.

    **Key Features:**

    * Region-specific consent policies (US and Global)
    * Immutable audit trails with timestamps and IP addresses
    * Multiple consent types (eSignAct, terms, marketing, SMS, email)
    * HATEOAS-based API navigation
    * User-initiated consent revocation
    * Complete change history tracking
  </Accordion>
</AccordionGroup>

## Multi-Tenant Architecture

The Baanx API automatically routes requests to the appropriate backend environment based on your client credentials. Each integration receives unique keys for sandbox and production environments.

<Note>
  **Required on ALL requests:** The `x-client-key` header must be included in every API call for proper routing.
</Note>

### Required Headers

| Header          | Required    | Description                                    |
| --------------- | ----------- | ---------------------------------------------- |
| `x-client-key`  | **Yes**     | Your public API key - required on all requests |
| `Authorization` | Conditional | Bearer token for authenticated endpoints       |
| `x-secret-key`  | Conditional | Secret key for OAuth endpoints only            |
| `x-us-env`      | Optional    | Set to `true` for US region routing            |

### Custom HTTP Status Codes

In addition to standard HTTP status codes, the API uses custom codes for specific scenarios:

* **498** - Invalid client key (check your `x-client-key` header)
* **499** - Missing client key (add `x-client-key` to request)

## Authentication

The Baanx API uses Bearer token authentication for protected endpoints. Tokens are obtained through either the OAuth 2.0 flow or direct login.

### Token Types

<Warning>
  Understanding the different token types is critical for proper API integration.
</Warning>

| Token Type        | Purpose                 | Lifetime   | Usage                                                          |
| ----------------- | ----------------------- | ---------- | -------------------------------------------------------------- |
| **JWT Token**     | OAuth flow session only | 10 minutes | Used only within authorization flow, not for API calls         |
| **Access Token**  | API authentication      | 6 hours    | Include in `Authorization: Bearer` header for all API requests |
| **Refresh Token** | Token renewal           | 184 days   | Exchange for new access tokens when they expire                |

### Getting Access Tokens

<CodeGroup>
  ```bash Direct Login theme={null}
  POST /v1/auth/login
  Content-Type: application/json
  x-client-key: YOUR_PUBLIC_KEY

  {
    "username": "user@example.com",
    "password": "secure_password"
  }

  # Response includes access_token
  {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 21600
  }
  ```

  ```bash OAuth Flow theme={null}
  # Step 1: Initiate (get hosted UI URL)
  GET /v1/auth/oauth/authorize/initiate?client_id=...&code_challenge=...

  # Step 2: User authenticates in hosted UI

  # Step 3: Exchange code for tokens
  POST /v1/auth/oauth/token
  Content-Type: application/json

  {
    "grant_type": "authorization_code",
    "code": "auth_code_from_callback",
    "code_verifier": "original_verifier",
    "redirect_uri": "https://yourapp.com/callback"
  }

  # Response includes access_token
  {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 21600
  }
  ```
</CodeGroup>

### Using Access Tokens

Include the access token in the `Authorization` header for all authenticated requests:

```bash theme={null}
GET /v1/user/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
x-client-key: YOUR_PUBLIC_KEY
```

### Refreshing Tokens

When your access token expires, use the refresh token to obtain a new one:

```bash theme={null}
POST /v1/auth/oauth/token
Content-Type: application/json
x-client-key: YOUR_PUBLIC_KEY
x-secret-key: YOUR_SECRET_KEY

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

## Environments

The API supports multiple environments for different use cases:

<CardGroup cols={2}>
  <Card title="Production" icon="globe">
    Live environment with real user data and transactions. Use production credentials for live applications.
  </Card>

  <Card title="Sandbox" icon="flask">
    Testing environment with isolated data. Use sandbox credentials for development and testing.
  </Card>
</CardGroup>

<Tip>
  Always test your integration thoroughly in the sandbox environment before moving to production.
</Tip>

## Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. If you exceed rate limits, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating when you can retry.

<Note>
  Contact your account manager for information about rate limits specific to your plan.
</Note>

## Error Handling

All error responses follow a consistent format:

```json theme={null}
{
  "error": "error_code",
  "error_description": "Human-readable description of what went wrong",
  "details": {
    "field": "Additional context when applicable"
  }
}
```

Common error scenarios:

* **400 Bad Request** - Invalid request parameters or body
* **401 Unauthorized** - Missing or invalid authentication
* **403 Forbidden** - Valid authentication but insufficient permissions
* **404 Not Found** - Resource does not exist
* **498 Invalid Client Key** - Check your `x-client-key` header
* **499 Missing Client Key** - Add `x-client-key` to your request
* **500 Internal Server Error** - Contact support if persistent

## Getting Help

<CardGroup cols={2}>
  <Card title="Integration Guides" icon="book-open" href="/guides/oauth/quickstart">
    Follow step-by-step guides for common integration patterns
  </Card>

  <Card title="Support" icon="headset">
    Contact your account manager for technical support and questions
  </Card>
</CardGroup>

## Next Steps

Ready to get started? Here are some recommended paths:

1. **New to the API?** Start with the [OAuth Quickstart](/guides/oauth/quickstart) to understand authentication
2. **Building a card application?** Check out [Card Operations](/guides/card/overview)
3. **Need regulatory compliance?** Review [Consent Management](/guides/consent/overview) for GDPR/CCPA requirements
4. **Implementing wallets?** Review [Wallet Management](/guides/wallet/custodial/index) (custodial) or [Delegation Flow](/guides/delegation/overview) (non-custodial)
5. **Testing integration?** Review [Troubleshooting](/guides/oauth/troubleshooting) for common issues