Authentication For Apps

Authentication ensures that all requests made to the Tuku Pay Gateway are secure and identifiable to the specific app. Below are the details and processes for app authentication.

Authentication Overview

1. App-Specific Credentials:

   • Each app is issued:

     • A unique app ID (appId) for identification.

     • An API key (apiKey) for secure authentication of requests.

   • The appId and apiKey must be included in the headers of every API request.

2. Token-Based Authentication (Optional Advanced Security):

   • Apps may also implement a token-based authentication system using a secret key for generating short-lived tokens.

   • This provides an extra layer of security, especially for apps with sensitive operations.

3. Security Measures:

   • All API requests must be made over HTTPS.

   • Requests from unregistered or non-whitelisted servers will be rejected.

   • Apps should securely store their apiKey and never expose it publicly.

---

Authentication Process

1. Obtaining App Credentials

When an app is registered, it is issued the following:

• App ID (appId): A globally unique identifier for the app.

• API Key (apiKey): A secure key for authenticating all requests.

Example Response Upon Registration:

{
  "appId": "abc123",
  "apiKey": "xyz789",
  "status": "active",
  "message": "App registered successfully."
}

2. Authenticating API Requests

All API requests must include the following headers for authentication:

Request Headers:

http Authorization: Bearer xyz789
X-App-ID: abc123

• Authorization: Contains the API key of the app.

• X-App-ID: Contains the unique app ID.

Example Request:

http POST /api/transactions/create HTTP/1.1
Host: api.tuku.money
Authorization: Bearer xyz789
X-App-ID: abc123
Content-Type: application/json

{
  "amount": 1000,
  "currency": "KES",
  "recipient": "0722000000"
}

---

Endpoints for Managing Authentication

1. Regenerate API Key

Used to regenerate an API key in case it is compromised.

Method: POST

URL: /api/apps/{appId}/regenerate-api-key

Request Headers:

http Authorization: Bearer xyz789
X-App-ID: abc123

Response:

{
  "status": "success",
  "newApiKey": "newApiKey123456",
  "message": "API key regenerated successfully. Please update your app with the new key."
}

---

2. Validate API Key

Checks the validity of an app’s API key.

Method: GET

URL: /api/auth/validate-key

Request Headers:

http Authorization: Bearer xyz789
X-App-ID: abc123

Response (Valid Key):

{
  "status": "valid",
  "appId": "abc123",
  "message": "API key is valid."
}

Response (Invalid Key):

{
  "status": "invalid",
  "message": "API key is invalid or expired."
}

---

Optional: Token-Based Authentication

For advanced security, apps can generate tokens using a secret key. These tokens are short-lived and tied to specific requests.

Token Generation (App Side)

Apps can generate tokens using a secret key provided during registration. The token payload may include:

• appId

• timestamp

• request payload (hashed)

Example Token:

{
  "appId": "abc123",
  "timestamp": "2024-12-19T12:00:00Z",
  "hash": "098f6bcd4621d373cade4e832627b4f6"
}

---

Best Practices for Authentication

1. Secure Storage:

   • Store the apiKey in a secure environment (e.g., environment variables).

   • Avoid hardcoding credentials into source code or exposing them in client-side code.

2. Key Rotation:

   • Periodically regenerate the apiKey to reduce security risks.

3. Monitor Usage:

   • Monitor app activity and track API usage logs to detect unauthorized access or anomalies.

4. IP Whitelisting:

   • Whitelist only trusted IP addresses or server domains for your app.

5. Use HTTPS:

   • Always use HTTPS for secure communication with the Tuku Pay Gateway.

---

Notes

1. Authentication Failure: Any request without valid credentials will be rejected with a 401 Unauthorized status.

2. Custom Headers:

   • Apps may include additional headers for specific functionality or customizations.

3. Audit Logs:

   • All authentication requests and token generations are logged for auditing purposes.

4. Error Responses: Authentication errors will include a detailed error message. Example:

   {
     "status": "error",
     "code": 401,
     "message": "Invalid API key."
   }