KRA Portal API Overview

The KRA Portal module integrates with Kenya Revenue Authority's developer.go.ke API gateway, providing programmatic access to 22 KRA services through a unified Salami Gateway interface. Validate PINs, check tax compliance, generate payment references, file returns, and more -- all via simple REST calls.

Table of Contents

1. What It Covers
2. Architecture
3. Authentication Flow
4. KRA App Model
5. Environments
6. API Categories
7. Base URL
8. Required Scopes
9. Rate Limiting
10. Error Handling

What It Covers

Salami wraps 22 developer.go.ke APIs across six categories:

Architecture

Your Application
       |
       v
  Salami Gateway API   (Bearer token auth)
       |
       v
  KRA App Credentials  (per-app consumer key/secret)
       |
       v
  developer.go.ke      (OAuth2 client_credentials)
       |
       v
   KRA Backend Systems

Each request flows through three layers:

1. Your app authenticates to Salami with a Bearer token (Sanctum)
2. Salami looks up the KRA App's stored credentials
3. Salami obtains an OAuth token from KRA and proxies the request

Authentication Flow

KRA's developer.go.ke uses OAuth 2.0 Client Credentials grant:

1. Register an application on developer.go.ke
2. Subscribe to the APIs you need (checkers, payments, etc.)
3. Obtain your Consumer Key and Consumer Secret
4. Store these in a KRA App within Salami

Token generation (handled automatically by Salami):

POST https://sbx.kra.go.ke/v1/token/generate?grant_type=client_credentials
Authorization: Basic base64(consumer_key:consumer_secret)

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Salami caches the token and refreshes it automatically with a 60-second safety buffer before expiry.

KRA App Model

Each KRA integration is configured through a KRA App record. A single tenant can have multiple KRA Apps (e.g., one sandbox app for testing, one production app for live use).

App Types

KRA App Fields

Environments

Switching Environments

Each KRA App has its own environment setting. To test:

1. Create a KRA App with environment: sandbox and sandbox credentials from developer.go.ke
2. Run all your tests against it
3. Create a separate KRA App with environment: production and production credentials
4. Point your production API calls to the production app ID

Important: Sandbox and production credentials are different. You cannot use sandbox credentials with the production endpoint or vice versa.

API Categories

Checkers (13 endpoints)

Read-only validation and lookup services. No side effects on KRA systems.

• PIN Validation
• PIN by ID
• Tax Obligations
• TCC Validation
• Invoice Checker
• Customs Declaration
• IT Exemption
• VAT Exemption
• Import Certificate by Number
• Import Certificate by PIN
• Excise License by PIN
• Excise License by Number
• Tax Service Office

Payments (3 endpoints)

Generate Payment Reference Numbers (PRNs) for withholding tax remittance.

• IT Withholding PRN
• Rental Withholding PRN
• VAT Withholding PRN

Compliance (1 endpoint)

Tax Compliance Certificate management.

• TCC Application

Registration (1 endpoint)

New taxpayer registration.

• Individual PIN Registration

Returns (2 endpoints)

Tax return filing.

• TOT Return
• NIL Return

Customs (1 endpoint)

Customs and border operations.

• Declaration Status

Base URL

All KRA Portal API requests go through your Salami tenant:

https://yourtenant.salami.dgl.co.ke/api/kra/

Required Scopes

Scope Groups

Rate Limiting

• Salami rate limit: 200 requests per minute per token
• KRA rate limits: Vary by API; typically 60 requests per minute per consumer key
• Salami caches OAuth tokens to minimize token generation calls

Error Handling

Salami-Level Errors

{
  "success": false,
  "message": "Your API token does not have the required permissions to access this endpoint.",
  "error": "insufficient_scope",
  "required_route": "api.kra.checkers.pin",
  "your_scopes": ["kra:apps"]
}

KRA-Level Errors

{
  "success": false,
  "message": "KRA API error: Invalid PIN format",
  "error": "kra_error",
  "kra_response": {
    "errorCode": "400",
    "errorMessage": "Invalid PIN format"
  }
}

Common Error Scenarios

Next Steps

• KRA App Management -- Create and test your KRA Apps
• KRA Checkers -- PIN validation and lookup APIs
• KRA Payments -- PRN generation for withholding taxes
• KRA Compliance -- TCC applications
• KRA Returns -- TOT and NIL return filing
• KRA Registration -- Individual PIN registration
• KRA Customs -- Customs declaration checking

Back to: Getting Started | eTIMS API | Account Tokens