Skip to main content

​
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

EnvironmentAuthenticationAPI Gateway
Sandboxhttps://identity-sandbox.sparkle.fyihttps://api-sandbox.sparkle.fyi
Productionhttps://identity.sparkle.nghttps://api.sparkle.ng
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

​
Registration

Dynamic Client Registration
  • Register your application and obtain client credentials
  • Supports both sandbox (instant) and production (approval required) environments
  • 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

EnvironmentRate LimitBurst Limit
Sandbox100 requests/minute200 requests/minute
Production10 requests/minute20 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: 
{
  "status": "success|error",
  "message": "Human-readable message",
  "data": {
    // Response data specific to the endpoint
  }
}

​
Error Response Format

{
  "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
  • 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: 
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: 
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 Support

​
Status & Updates

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