KRA App Management

KRA Apps store your developer.go.ke credentials and eTIMS device configurations. Each app represents a single set of credentials tied to a specific environment (sandbox or production).

Table of Contents

1. Overview
2. Endpoints
3. List KRA Apps
4. Test KRA App Credentials
5. Creating KRA Apps
6. Environment Switching
7. Best Practices

Overview

Required Scope

Endpoint Summary

List KRA Apps

Retrieve all KRA apps configured for your tenant.

Endpoint: GET /api/kra/apps

Required Scope: kra:apps

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/kra/apps \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "KRA Sandbox Portal",
      "type": "portal",
      "environment": "sandbox",
      "is_active": true,
      "last_used_at": "2026-03-28T14:30:00Z",
      "created_at": "2026-03-01T10:00:00Z"
    },
    {
      "id": 2,
      "name": "Production Portal",
      "type": "portal",
      "environment": "production",
      "is_active": true,
      "last_used_at": "2026-03-29T08:15:00Z",
      "created_at": "2026-03-15T09:00:00Z"
    },
    {
      "id": 3,
      "name": "eTIMS Main Branch",
      "type": "etims",
      "environment": "production",
      "is_active": true,
      "last_used_at": "2026-03-29T11:45:00Z",
      "created_at": "2026-03-10T14:00:00Z"
    }
  ]
}

Response Fields

Note: Credentials (consumer_key, consumer_secret, cmc_key) are never returned in API responses for security.

Test KRA App Credentials

Verify that a KRA app's credentials are valid by attempting to generate an OAuth access token from KRA.

Endpoint: POST /api/kra/apps/{id}/test

Required Scope: kra:apps

Path Parameters:

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/kra/apps/1/test \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Accept: application/json'

Success Response (200):

{
  "success": true,
  "data": {
    "app_id": 1,
    "app_name": "KRA Sandbox Portal",
    "environment": "sandbox",
    "status": "connected",
    "token_generated": true,
    "token_expires_in": 3600,
    "tested_at": "2026-03-29T12:00:00Z"
  },
  "message": "KRA credentials are valid. Token generated successfully."
}

Failure Response (422):

{
  "success": false,
  "data": {
    "app_id": 1,
    "app_name": "KRA Sandbox Portal",
    "environment": "sandbox",
    "status": "failed",
    "token_generated": false
  },
  "message": "Failed to generate access token. Please verify your consumer key and secret.",
  "error": "kra_auth_failed"
}

Test Behavior by App Type

Creating KRA Apps

KRA Apps are created through the Salami dashboard:

1. Navigate to KRA > KRA Apps > Add New
2. Select the app type:
   • Portal for developer.go.ke APIs
   • eTIMS for OSCU integration
3. Fill in credentials:

Portal App Fields

eTIMS App Fields

Environment Switching

Recommended Setup

Create two portal apps per use case:

App #1: "Sandbox Portal"    → environment: sandbox
App #2: "Production Portal" → environment: production

How Environment Affects Requests

Testing Workflow

1. Create sandbox KRA App with sandbox credentials
2. Test credential validity: POST /api/kra/apps/1/test
3. Run all your integration tests against the sandbox app
4. Create production KRA App with production credentials
5. Test production credential validity: POST /api/kra/apps/2/test
6. Switch your application to use the production app ID

Best Practices

1. Separate apps per environment -- Never reuse sandbox credentials in production
2. Test before use -- Always verify credentials with the test endpoint after setup
3. Name clearly -- Use descriptive names like "Production WHT Portal" or "Sandbox Checkers"
4. Deactivate unused apps -- Set is_active: false for retired configurations
5. Rotate secrets -- Periodically regenerate consumer secrets on developer.go.ke and update the app
6. One app per subscription -- If you have different API subscriptions on developer.go.ke, create separate apps

Status Codes

Related Documentation

• KRA Overview -- Architecture and authentication flow
• KRA Checkers -- PIN validation and lookup APIs
• eTIMS Device -- eTIMS device setup and configuration

Back to: KRA Overview | Getting Started