Skip to main content

MPesa MSISDN Decrypter API

The MPesa MSISDN Decrypter API is a secure service enabling users to decrypt masked MSISDN (phone numbers) and perform database management tasks associated with MSISDN data. This API facilitates mobile security and data access management, primarily designed to support applications that require secure access to mobile data.

Key Features​

  1. Authentication
    All API endpoints require an authentication token, obtained via the /auth/get-token endpoint. This token must be included in the request headers as a Bearer token to ensure secure access to each endpoint.

  2. Data Decryption and Retrieval
    The API offers endpoints to decrypt hashed phone numbers and retrieve MSISDN details. This feature supports applications needing secure access to the original phone numbers based on a unique hash.

  3. Database Operations
    The API includes endpoints to generate, split, and rehydrate the database containing MSISDN details. These functions provide flexibility and scalability in managing the underlying database resources.

API Endpoints​

1. Home Endpoint​

  • Endpoint: /
  • Method: GET
  • Operation: Home
  • Description: Basic access point that returns a simple message or confirmation response.
  • Responses:
    • 200 OK: Successful response with a string.
    • 401 Unauthorized: Access denied due to missing or invalid token.

2. Get Token​

  • Endpoint: /auth/get-token
  • Method: POST
  • Operation: GetToken
  • Description: Authenticates the user and provides a token required for accessing all other endpoints.
  • Responses:
    • 200 OK: Successful retrieval of the authentication token.
    • 404 Not Found: Authentication failed or endpoint not found.

3. Decrypt Phone Number by Hash​

  • Endpoint: /decrypt/{hash}
  • Method: GET
  • Operation: GetPhoneNumberByHash
  • Description: Takes a hash as input and returns the corresponding MSISDN.
  • Path Parameter:
    • hash (string, required): The unique hash representing a phone number.
  • Responses:
    • 200 OK: Successful decryption and retrieval of the MSISDN details.
    • 401 Unauthorized: Access denied due to missing or invalid token.

4. Add User​

  • Endpoint: /users/add
  • Method: POST
  • Operation: AddUser
  • Description: Adds a new user to the system. (Details regarding input are unspecified and may be configured as per user management protocols).
  • Responses:
    • 200 OK: User added successfully.
    • 404 Not Found: User addition failed or endpoint not found.

5. Split Database​

  • Endpoint: /db/split
  • Method: POST
  • Operation: SplitDatabase
  • Description: Splits the MSISDN database, possibly for load balancing or data organization.
  • Responses:
    • 200 OK: Database split operation successful.
    • 401 Unauthorized: Access denied due to missing or invalid token.

6. Rehydrate Database​

  • Endpoint: /db/rehydrate
  • Method: POST
  • Operation: RehydrateDatabase
  • Description: Rehydrates (reloads or restores) the MSISDN database, potentially useful after backup or downtime.
  • Responses:
    • 200 OK: Database rehydration successful, returns MSISDN details.
    • 401 Unauthorized: Access denied due to missing or invalid token.

7. Generate Database​

  • Endpoint: /db/generate
  • Method: POST
  • Operation: GenerateDatabase
  • Description: Generates a new MSISDN database. This may be an initialization step or data migration task.
  • Responses:
    • 200 OK: Database generation successful, returns MSISDN details.
    • 401 Unauthorized: Access denied due to missing or invalid token.

Data Schema​

PhoneNumber Object​

FieldTypeRequiredDescription
hashstringYesUnique identifier hash
msisdnstringYesDecrypted MSISDN

The PhoneNumber object represents decrypted MSISDN data and consists of two required fields: a hash and the msisdn itself.

Authentication Requirement​

Each request (except token generation) must include the following header for authorization:

Authorization: Bearer {token}

Replace {token} with the value obtained from the /auth/get-token endpoint.

This API documentation provides a structured approach to understanding and implementing the MPesa MSISDN Decrypter API for secure mobile number decryption and database management functions. Each endpoint is designed with security in mind, requiring token-based authentication, and supports core operations for mobile number decryption and database management within applications.