API Authentication and Encryption Documentation

📋 Overview

This document outlines the authentication and encryption mechanisms used for secure communication between client applications and backend services. The system employs a combination of OAuth-style authentication and asymmetric encryption to ensure data security and proper access control.

⚠️ Quick Reference - Key Usage Rule

🔑 Remember: Always encrypt outgoing data with the recipient's public key and decrypt incoming data with your own private key.

1. 🎫 Credential Structure

Each client application receives a comprehensive set of credentials containing the following components:

🔑 Consumer Key & Secret: Used for API authentication and token generation
🏷️ Agent Identifier: Unique identifier for your application instance
🔓 Public Key: Used for encrypting data sent to your application
🔒 Private Key: Used for decrypting data received by your application

2. 🔐 Authentication Flow

🎟️ Token Generation

Purpose: All API access requires authentication tokens
Process: Generate tokens using your assigned consumer key and consumer secret
Usage: Include the generated token in all API requests for authentication

🏷️ Agent Parameter

Requirement: Many APIs require an agent parameter in requests
Rule: Always use the agent identifier provided in your credential set. Do NOT use generic agents (e.g., "SAFARICOM-CONSORTIUM-SANDBOX-") - use your specifically assigned agent

3. 🔄 Encryption Principles

The encryption system follows asymmetric cryptography principles with role-specific key usage:

📊 Data Flow Direction and Key Usage

📥 Receiving Data (Backend → Your Application)

🔐 Encryption: Backend uses YOUR public key to encrypt data
🔓 Decryption: YOUR application uses YOUR private key to decrypt received data
📋 Key Rule: Always use your own private key for decryption

📤 Sending Data (Your Application → Backend)

🔐 Encryption: YOUR application uses the BACKEND'S public key to encrypt data
🔓 Decryption: Backend uses their own private key to decrypt received data
📋 Key Rule: Use the specific backend's public key for encryption

4. 🏢 Example | Backend-Specific Implementation

🏥 Afyayangu Integration

🔐 Authentication: Use your assigned consumer key, secret, and agent (not Afyayangu agent)
📱 PIN Encryption: When calling cr-validate-pin API:
- Encrypt the PIN using Afyayangu's public key
- Include YOUR assigned agent in request parameters
📊 General Data: Use Afyayangu's public key for encrypting data sent to Afyayangu

🏥 HealthPro Backend Integration

🔐 Authentication: Use your assigned credentials for token generation
📊 Data Encryption: Use HealthPro's public key for encrypting data sent to HealthPro
🏷️ Agent Parameter: Use your assigned agent in API requests where necessary

5. 🛡️ Key Management Best Practices

🔓 Public Key Distribution

Each backend service provides their public key to client applications
Store backend public keys securely and associate them with the correct service
Verify public key authenticity through secure channels

🔒 Private Key Security

Keep your private key confidential and secure
Never share your private key with external parties
Use your private key exclusively for decrypting data intended for your application

6. ⚙️ Implementation Workflow

📋 Step 1: Initialize Credentials

1. Receive credential set from service provider
2. Securely store all credential components
3. Validate that all required components are present

🔑 Step 2: Authentication Setup

1. Generate access token using consumer key and secret
2. Configure API client with generated token
3. Set agent parameter to your assigned agent identifier

🔐 Step 3: Encryption Configuration

1. Store your private key for decryption operations
2. Obtain and store public keys for each backend service
3. Implement encryption/decryption functions with appropriate key selection

🚀 Step 4: API Communication

For outgoing requests:
1. Identify target backend service
2. Select appropriate backend public key
3. Encrypt sensitive data using backend's public key
4. Include encrypted data in API request

For incoming responses:
1. Receive encrypted data from backend
2. Use your private key to decrypt the data
3. Process decrypted information

7. 🛡️ Security Considerations

🌐 Data in Transit

All sensitive data must be encrypted before transmission
Use TLS/HTTPS for transport layer security
Implement proper error handling to avoid information leakage

🔄 Key Rotation

Monitor for public key updates from backend services
Implement secure key update mechanisms
Maintain backward compatibility during key transitions

⚠️ Error Handling

Never log decrypted sensitive data
Implement secure error messages that don't expose encryption details
Use proper exception handling for encryption/decryption failures

8. 🔧 Troubleshooting

❌ Common Issues

🔐 Authentication Failures: Verify consumer key, secret, and agent parameters
🔓 Decryption Errors: Ensure you're using your private key, not a public key
🔒 Encryption Failures: Confirm you're using the correct backend's public key

✅ Validation Steps

Verify credential completeness and format
Test token generation with consumer key and secret
Validate encryption/decryption with test data
Confirm agent parameter usage in API calls

💡 Final Reminder

🔑 Always encrypt outgoing data with the recipient's public key and decrypt incoming data with your own private key.