Authentication API

Authentication API

Overview

The Buburuza Authentication API provides secure access to all platform services using JWT tokens, OAuth 2.0, and optional biometric authentication. Built with bank-grade security standards and designed for both B2B integrations and consumer applications.

Authentication Methods

1. API Key Authentication (Server-to-Server)

For backend services and server-to-server communication.

curl -X GET https://api.buburuza.com/v1/customers \
  -H "Authorization: Bearer bb_live_1234567890abcdef" \
  -H "Content-Type: application/json"

2. OAuth 2.0 (User Authentication)

For applications that need to act on behalf of users.

// Redirect users to Buburuza OAuth
const authUrl = buburuza.auth.getAuthorizationUrl({
  clientId: 'your_client_id',
  redirectUri: 'https://yourapp.com/callback',
  scope: ['accounts:read', 'transactions:write'],
  state: 'random_state_string'
});

window.location.href = authUrl;

3. Biometric Authentication (Mobile)

For enhanced security on mobile applications.

// Request biometric authentication
const biometricAuth = await buburuza.auth.requestBiometric({
  userId: 'user_123',
  method: 'fingerprint', // 'fingerprint', 'face', 'voice'
  challenge: 'auth_challenge_456'
});

API Endpoints

Generate Access Token

Exchange credentials for a JWT access token.

POST /v1/auth/token

const tokenResponse = await fetch('https://api.buburuza.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    scope: 'accounts transactions'
  })
});

const { access_token, token_type, expires_in } = await tokenResponse.json();

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "accounts transactions",
  "refresh_token": "rt_1234567890abcdef"
}

Refresh Access Token

Obtain a new access token using a refresh token.

POST /v1/auth/refresh

const refreshResponse = await buburuza.auth.refreshToken({
  refreshToken: 'rt_1234567890abcdef'
});

console.log('New access token:', refreshResponse.accessToken);

Request:

{
  "grant_type": "refresh_token",
  "refresh_token": "rt_1234567890abcdef"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_0987654321fedcba"
}

Validate Token

Verify the validity and scope of an access token.

GET /v1/auth/validate

const validation = await buburuza.auth.validateToken({
  token: access_token
});

console.log('Token valid:', validation.valid);
console.log('Scopes:', validation.scopes);

Response:

{
  "valid": true,
  "expires_at": "2025-11-07T16:30:00Z",
  "scopes": ["accounts:read", "transactions:write"],
  "client_id": "your_client_id",
  "user_id": "user_123"
}

Revoke Token

Revoke an access or refresh token.

POST /v1/auth/revoke

await buburuza.auth.revokeToken({
  token: access_token,
  token_type: 'access_token'
});

OAuth 2.0 Flows

Authorization Code Flow

For web applications with secure backend.

Step 1: Authorization Request

const authUrl = `https://auth.buburuza.com/oauth/authorize?` +
  `response_type=code&` +
  `client_id=${clientId}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `scope=accounts transactions&` +
  `state=${state}`;

// Redirect user to authUrl

Step 2: Exchange Code for Token

const tokenResponse = await fetch('https://api.buburuza.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    code: 'authorization_code_from_callback',
    redirect_uri: 'https://yourapp.com/callback'
  })
});

Client Credentials Flow

For machine-to-machine authentication.

const clientAuth = await buburuza.auth.clientCredentials({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  scope: ['accounts:read', 'transactions:write']
});

// Use the returned access token for API calls

PKCE Flow (Mobile Apps)

For mobile applications without secure storage.

import { generateCodeChallenge, generateCodeVerifier } from '@buburuza/sdk';

// Step 1: Generate PKCE parameters
const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);

// Step 2: Authorization request with PKCE
const authUrl = `https://auth.buburuza.com/oauth/authorize?` +
  `response_type=code&` +
  `client_id=${clientId}&` +
  `redirect_uri=${redirectUri}&` +
  `code_challenge=${codeChallenge}&` +
  `code_challenge_method=S256&` +
  `scope=accounts transactions`;

// Step 3: Exchange code with verifier
const tokenResponse = await buburuza.auth.exchangeCodeForToken({
  code: authorizationCode,
  codeVerifier: codeVerifier,
  clientId: 'your_client_id'
});

Biometric Authentication

Setup Biometric Authentication

Register biometric credentials for a user.

POST /v1/auth/biometric/register

const biometricRegistration = await buburuza.auth.biometric.register({
  userId: 'user_123',
  biometricType: 'fingerprint',
  deviceId: 'device_456',
  publicKey: biometricPublicKey, // Generated by device
  metadata: {
    deviceModel: 'iPhone 14 Pro',
    osVersion: 'iOS 16.1'
  }
});

Authenticate with Biometrics

Verify user identity using biometric data.

POST /v1/auth/biometric/verify

const biometricAuth = await buburuza.auth.biometric.verify({
  userId: 'user_123',
  challenge: 'auth_challenge_789',
  signature: biometricSignature, // Signed challenge
  biometricType: 'fingerprint'
});

if (biometricAuth.verified) {
  console.log('Biometric authentication successful');
  // Access token provided in response
}

Scopes and Permissions

Available Scopes

Scope	Description	Access Level
accounts:read	Read account information and balances	Read-only
accounts:write	Create and modify accounts	Read/Write
transactions:read	View transaction history	Read-only
transactions:write	Create transactions and transfers	Read/Write
cards:read	View card information	Read-only
cards:write	Issue and manage cards	Read/Write
investments:read	View portfolio and positions	Read-only
investments:write	Execute trades and manage portfolio	Read/Write
kyc:read	View KYC status and documents	Read-only
kyc:write	Initiate and manage KYC processes	Read/Write
ai:read	Access AI insights and analytics	Read-only
ai:write	Submit requests to AI services	Read/Write

Scope Examples

// Request minimal scopes for read-only access
const readOnlyToken = await buburuza.auth.clientCredentials({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  scope: ['accounts:read', 'transactions:read']
});

// Request comprehensive scopes for full functionality
const fullAccessToken = await buburuza.auth.clientCredentials({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  scope: [
    'accounts:write',
    'transactions:write',
    'cards:write',
    'investments:write'
  ]
});

Security Best Practices

Token Storage

// ✅ Secure token storage
localStorage.setItem('buburuza_access_token', access_token);
localStorage.setItem('buburuza_refresh_token', refresh_token);

// ✅ Even better: Use secure HTTP-only cookies
// Set tokens in secure cookies on your backend
res.cookie('access_token', access_token, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  maxAge: 3600000 // 1 hour
});

Token Refresh Strategy

class BuburuざAuthManager {
  constructor(apiKey, refreshToken) {
    this.apiKey = apiKey;
    this.refreshToken = refreshToken;
    this.accessToken = null;
    this.tokenExpiry = null;
  }

  async getValidToken() {
    // Check if current token is still valid
    if (this.accessToken && this.tokenExpiry > Date.now()) {
      return this.accessToken;
    }

    // Refresh token if expired
    const tokenResponse = await this.refreshAccessToken();
    this.accessToken = tokenResponse.access_token;
    this.tokenExpiry = Date.now() + (tokenResponse.expires_in * 1000);
    
    return this.accessToken;
  }

  async makeAuthenticatedRequest(endpoint, options = {}) {
    const token = await this.getValidToken();
    
    return fetch(`https://api.buburuza.com${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
  }
}

Error Handling

async function makeSecureApiCall(endpoint, data) {
  try {
    const response = await buburuza.api.request(endpoint, data);
    return response;
  } catch (error) {
    switch (error.code) {
      case 'invalid_token':
        // Token is invalid or expired
        await refreshAccessToken();
        return makeSecureApiCall(endpoint, data); // Retry
        
      case 'insufficient_scope':
        // Token doesn't have required permissions
        throw new Error('Application needs additional permissions');
        
      case 'rate_limit_exceeded':
        // Too many requests
        await new Promise(resolve => setTimeout(resolve, 1000));
        return makeSecureApiCall(endpoint, data); // Retry after delay
        
      default:
        throw error;
    }
  }
}

Multi-Factor Authentication (MFA)

Enable MFA for User

POST /v1/auth/mfa/enable

const mfaSetup = await buburuza.auth.mfa.enable({
  userId: 'user_123',
  method: 'totp', // 'totp', 'sms', 'email'
  phoneNumber: '[phone]' // Required for SMS
});

console.log('MFA Secret:', mfaSetup.secret);
console.log('QR Code URL:', mfaSetup.qrCodeUrl);

Verify MFA Code

POST /v1/auth/mfa/verify

const mfaVerification = await buburuza.auth.mfa.verify({
  userId: 'user_123',
  code: '123456',
  method: 'totp'
});

if (mfaVerification.verified) {
  // Grant access to sensitive operations
  console.log('MFA verification successful');
}

Webhook Authentication

Verify webhook requests are from Buburuza.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Express.js webhook handler
app.post('/webhooks/buburuza', (req, res) => {
  const signature = req.headers['x-buburuza-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook event
  const event = req.body;
  console.log('Verified webhook event:', event.type);
  
  res.status(200).send('OK');
});

Rate Limiting

The Authentication API implements rate limiting to prevent abuse:

• Token requests: 10 per minute per IP

• Token validation: 100 per minute per token

• Biometric authentication: 5 per minute per user

// Handle rate limiting gracefully
async function authenticateWithRetry(credentials, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await buburuza.auth.authenticate(credentials);
    } catch (error) {
      if (error.code === 'rate_limit_exceeded' && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Testing Authentication

Sandbox Environment

// Use test credentials in sandbox
const sandboxAuth = new BuburuざAPI({
  apiKey: 'bb_test_1234567890abcdef',
  environment: 'sandbox'
});

// Test authentication flow
const testToken = await sandboxAuth.auth.clientCredentials({
  clientId: 'test_client_123',
  clientSecret: 'test_secret_456',
  scope: ['accounts:read', 'transactions:write']
});

Mock Biometric Authentication

// Sandbox automatically approves biometric requests
const mockBiometric = await sandboxAuth.auth.biometric.verify({
  userId: 'test_user_123',
  challenge: 'test_challenge',
  signature: 'mock_signature',
  biometricType: 'fingerprint'
});

console.log('Mock biometric result:', mockBiometric.verified); // true

---

Support and Resources

• Authentication Guide: Detailed implementation examples

• Security Best Practices: Industry-standard security recommendations

• Troubleshooting: Common authentication issues and solutions

• SDKs: Pre-built authentication handling in all supported languages

For additional help, contact our developer support team at [email protected].