Authentication

The SDK uses OAuth 2.0 password grant flow for authentication.

Basic Authentication

const client = createInstance({
  baseUrl: 'https://api.cloud.mbanq.com',
  tenantId: 'your-tenant-id'
});

await client.connect({
  credential: {
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    username: 'your-username',
    password: 'your-password',
    grant_type: 'password'
  }
});

Additional Configuration Options

const client = createInstance({
  // Required configuration
  baseUrl: 'https://api.cloud.mbanq.com',
  tenantId: 'your-tenant-id',
  
  // Optional configuration
  axiosConfig: {
    timeout: 30000, // Request timeout in milliseconds (default: 29000)
    keepAlive: true, // HTTP keep-alive for connection reuse
    headers: {
      'Custom-Header': 'custom-value' // Additional HTTP headers
    }
  }
});

Two-Factor Authentication (2FA)

If your account has Two-Factor Authentication (2FA) enabled, you must verify your identity using a One-Time Password (OTP) after the initial connection.

const client = createInstance({
  baseUrl: 'https://api.cloud.mbanq.com',
  tenantId: 'your-tenant-id'
});

// 1. Initial connection
// Returns 2FA status: { isMFARequired, mfaDeliveryMethods, isSelfServiceUser, isPasswordExpired }
const { isMFARequired, mfaDeliveryMethods } = await client.connect({
  credential: {
    client_id: 'your-client-id',
    client_secret: 'your-client-secret',
    username: 'your-username',
    password: 'your-password',
    grant_type: 'password'
  }
});

if (isMFARequired) {
  // 2. Perform 2FA verification if required
  // mfaDeliveryMethods contains available methods, e.g. ['TOTP']
  await client.twoFactorAuthentication({
    token: '123456', // The OTP code
    deliveryMethod: 'email'
  });
}

// 3. Perform authorized requests
try {
  const result = await client.request(CreatePayment({ /* ... */ }));
} catch (error) {
  // NOTE: If you receive an AUTHORIZATION_ERROR with code 'RESTRICTED' 
  // and message "Access to type ... is restricted", it means your 2FA token 
  // has expired. You must perform 2FA verification again.
  if (error.code === 'RESTRICTED') {
    await client.twoFactorAuthentication({ /* ... */ });
  }
}

Security Best Practices

Credential Management

• Never hardcode credentials in your source code
• Use environment variables or secure credential management systems
• Rotate API secrets and tokens regularly
• Use the minimum required permissions for your integration

Environment Variables Example

const client = createInstance({
  baseUrl: process.env.MBANQ_API_URL,
  tenantId: process.env.MBANQ_TENANT_ID
});

await client.connect({
  credential: {
    client_id: process.env.MBANQ_CLIENT_ID,
    client_secret: process.env.MBANQ_CLIENT_SECRET,
    username: process.env.MBANQ_USERNAME,
    password: process.env.MBANQ_PASSWORD,
    grant_type: 'password'
  }
});

Production Considerations

• Use HTTPS endpoints only (https://)
• Implement proper error handling to avoid credential leakage in logs
• Configure appropriate request timeouts
• Use connection pooling for high-volume applications

Axios Instance Logger

You can also configure an Axios instance logger to set up interceptors or other axios-specific configurations:

const axiosLogger = (axiosInstance) => {
  // Add request interceptor
  axiosInstance.interceptors.request.use(
    (config) => {
      console.log('Request:', config.method?.toUpperCase(), config.url);
      return config;
    }
  );
  
  // Add response interceptor
  axiosInstance.interceptors.response.use(
    (response) => {
      console.log('Response:', response.status, response.config.url);
      return response;
    }
  );
};

const coreSDK = createInstance({
  secret: 'testing123',
  signee: 'TESTING',
  baseUrl: 'https://example.com',
  tenantId: 'testing',
  logger: axiosLogger // Configure Axios instance
});