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

# Introduction

> Complete API documentation for Open Banking integration

# API Reference

This section provides detailed information about all available endpoints, authentication methods, request/response formats, and integration patterns.

## API Overview

Our Open Banking API provides secure access to financial data and payment services through RESTful endpoints. All APIs follow consistent patterns for authentication, error handling, and response formatting.

### Base URLs

| Environment    | Authentication                         | API Gateway                       |
| -------------- | -------------------------------------- | --------------------------------- |
| **Sandbox**    | `https://identity-sandbox.sparkle.fyi` | `https://api-sandbox.sparkle.fyi` |
| **Production** | `https://identity.sparkle.ng`          | `https://api.sparkle.ng`          |

<Note>
  Where `Authentication base url` is defined as `AUTH_BASE_URL`  anywhere in this documentation and `API Gateway base url` is defined as the variable `API_BASE_URL` anywhere in this documentation
</Note>

### Registration

**Dynamic Client Registration**

* Register your application and obtain client credentials
* Supports both sandbox (instant) and production (approval required) environments

### Customer Consent Approval

* Some API accessing Customer resource (e.g. account information, debiting account, etc) requires customer consent
* Some generic APIs `do not` require customer consent because customer resoruces are not accessed (e.g. Get Biller Categories, Get Billers etc)

## Rate Limits

| Environment    | Rate Limit          | Burst Limit         |
| -------------- | ------------------- | ------------------- |
| **Sandbox**    | 100 requests/minute | 200 requests/minute |
| **Production** | 10 requests/minute  | 20 requests/minute  |

## Error Handling

### HTTP Status Codes

* **200**: Success
* **201**: Created
* **400**: Bad Request
* **401**: Unauthorized
* **403**: Forbidden
* **404**: Not Found
* **429**: Too Many Requests
* **500**: Internal Server Error

### General Response Format

All API responses follow a consistent JSON format:

```json theme={null}
{
  "status": "success|error",
  "message": "Human-readable message",
  "data": {
    // Response data specific to the endpoint
  }
}
```

### Error Response Format

```json theme={null}
{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "amount",
      "code": "INVALID_AMOUNT",
      "message": "Amount must be greater than 0"
    }
  ]
}
```

## Security & Compliance

### Data Protection

* All data is encrypted in transit (TLS 1.2+)
* Sensitive data is encrypted at rest
* PCI DSS and ISO 27001 compliance
* Regular security audits

### Consent Management

* Fine-grained customer consent by resource
* Customer can revoke consent at any time
* Consent expiration and renewal
* Audit trail for all consent activities

### API Security

* OAuth 2.0 with PKCE support
* Request signing for integrity
* Idempotency keys for deduplication
* Rate limiting and throttling

## Getting Started

### 1. Register Your Application

Start by registering your application using Dynamic Client Registration:

```bash theme={null}
curl -X POST https://identity.sparkle.fyi/dcr \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-email@example.com",
    "password": "your-password",
    "app_name": "Your App Name",
    "app_description": "Description of your application",
    "app_developer_name": "Your Company Name",
    "app_developer_address": "Your Address",
    "app_developer_contact_email": "contact@example.com",
    "app_developer_contact_phone": "+2348012345678",
    "redirect_url": "https://yourapp.com/callback"
  }'
```

### 2. Implement OAuth Flow

Choose the appropriate OAuth flow for your application:

* **Authorization Code**: For web applications
* **Device Code**: For limited devices (TVs, IoT)
* **PKCE**: For single-page applications

### 3. Make Your First API Call

Test with a simple account listing request:

```bash theme={null}
curl -X GET https://api.sparkle.fyi/accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "signature: YOUR_SIGNATURE" \
  -H "idempotency_key: UNIQUE_REQUEST_ID"
```

## Best Practices

### Authentication

* Store access tokens securely
* Implement token refresh logic
* Handle token expiration gracefully
* Use appropriate OAuth flow for your use case

### Error Handling

* Always check HTTP status codes
* Parse error messages for user feedback
* Implement retry logic with exponential backoff
* Log errors for debugging

### Performance

* Cache responses when appropriate
* Use pagination for large datasets
* Implement request deduplication
* Monitor rate limits

### Security

* Never expose client secrets in client-side code
* Validate all input data
* Use HTTPS for all communications
* Implement proper session management

## Support Resources

### Documentation

* [Developer Onboarding](/guides/developer-onboarding) - Complete setup guide
* [Authentication Guide](/api-reference/authentication) - OAuth implementation details
* [Code Examples](/quickstart) - Ready-to-use code samples

### Developer Support

* **Email**: [developers@sparkle.ng](mailto:developers@sparkle.ng)
* **Support Portal**: [https://sparkle.ng/support](https://sparkle.ng/support)
* **Community Forum**: [https://community.sparkle.ng](https://community.sparkle.ng)

### Status & Updates

* **API Status**: [https://status.sparkle.ng](https://status.sparkle.ng)
* **Changelog**: [https://sparkle.ng/changelog](https://sparkle.ng/changelog)
* **Blog**: [https://sparkle.ng/blog](https://sparkle.ng/blog)

<Note>
  This API reference is continuously updated. Subscribe to our changelog to stay informed about new endpoints, features, and breaking changes.
</Note>

<Button href="/api-reference/authentication" size="sm">
  Start with Authentication
</Button>