Overview
The KRID API enables authorized partners (government agencies, financial institutions, healthcare providers, and approved third parties) to verify the identity of Katsina State residents. Built on a microservices architecture, the API provides secure, fast, and reliable identity verification.
Partner Verification
Verify KRID numbers, cross-check identity documents, and match faces.
Resident Services
Registration, authentication, profile management, and wallet operations.
Secure by Design
API key authentication, minimal data exposure, and full audit logging.
Authentication
The API uses two authentication methods depending on the endpoint type:
API Key
Used by external partner systems (e.g. KASEDA, SUBEB) for server-to-server verification requests.
X-API-Key: ik_live_your_key_hereBearer Token (JWT)
Used by citizen-facing applications after resident login via OTP.
Authorization: Bearer eyJhbG...Obtaining an API Key
- Submit a formal request to the iKatsina Digital Infrastructure Office
- Include your agency name, intended use case, and estimated request volume
- Sign the Data Usage Agreement (DUA)
- Receive your API key pair (test + production)
Base URL
https://api.ikatsina.nghttps://staging-api.ikatsina.ngAll endpoints are prefixed with /api. The Swagger interactive docs are available at /api/docs.
Rate Limits
| Tier | Requests / min | Requests / day |
|---|---|---|
| Standard | 60 | 10,000 |
| Premium | 300 | 100,000 |
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.
Verification API
These endpoints are for external partners to verify Katsina residents. Authenticated via X-API-Key.
Resident API
These endpoints power citizen-facing applications (KRID portal, mobile app). Authenticated via JWT Bearer token obtained through OTP login.
Response Format
All API responses follow a consistent envelope format:
{
"success": true,
"data": {
// Response payload
}
}{
"statusCode": 401,
"message": "Invalid API key",
"error": "Unauthorized"
}HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success. Request processed. |
| 201 | Created. Resident registered successfully. |
| 400 | Bad Request. Invalid input or validation error. |
| 401 | Unauthorized. Missing or invalid API key / JWT. |
| 403 | Forbidden. Insufficient permissions. |
| 404 | Not Found. Resident or resource does not exist. |
| 409 | Conflict. Duplicate NIN, BVN, phone, or face. |
| 429 | Too Many Requests. Rate limit exceeded. |
| 502 | Bad Gateway. Upstream service temporarily unavailable. |
KRID Status Values
Every resident has a status that determines what actions they can perform:
Active, verified resident. Eligible for all services.
Registration under review. Not yet eligible.
Account temporarily suspended by admin.
Registration was rejected. Must re-apply.
Quick Start
Verify a KRID number in under 30 seconds. Pick your language:
curl -X POST https://api.ikatsina.ng/api/verify/krid \
-H "Content-Type: application/json" \
-H "X-API-Key: ik_live_your_api_key_here" \
-d '{"kridNumber": "8392740001"}'SDKs & Examples
JavaScript / TypeScript
npm package with full TypeScript types
Python
pip package with async support
PHP
Composer package for Laravel / plain PHP
Swagger / OpenAPI
Interactive API explorer at /api/docs
Sandbox & Testing
Test Credentials
https://staging-api.ikatsina.ngik_test_partner_key_devTest KRID Numbers
| KRID | Status |
|---|---|
| 8392740001 | VERIFIED |
| 8392740002 | PENDING |
| 8392740003 | SUSPENDED |
| 0000000000 | Not Found |
Important
Sandbox data is reset periodically. Do not use test API keys in production. Production keys begin with ik_live_, test keys with ik_test_.
Support
Integration Support
For help with API integration, onboarding, and technical issues.
api-support@ikatsina.ngData Privacy
The API returns only minimal, non-sensitive data (first name, last name, LGA, state). Sensitive fields like NIN, BVN, phone, email, and face images are never returned. All verification requests are logged with partner ID for audit compliance.