Authentication

Overview

The K2 Telecom USSD API uses username/password authentication to obtain a JWT token for secure access to all endpoints.

Authentication Method

1. Login to get JWT token using username and password
2. Generate Service Unique ID using the JWT token (see Generate Service Unique ID)
3. Use the Service ID for API requests

Login Endpoint

URL: https://k2-ussd-api.devlorde.xyz/api/auth/login

Method: POST

Content-Type: application/json

Login Request

{
  "username": "your_username",
  "password": "your_password"
}

Login Response

{
  "status": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzcyI6IjE3NzY1NDIzIiwiaWQiOiI1Z",
    "user": {
      "id": "5eb0b71b-c6ed-4857-9ab5-d8152f3e0a55",
      "client_id": "17765423",
      "username": "weerinde",
      "email": "",
      "role": "admin",
      "is_active": 1,
      "msisdn": null,
      "created_at": "2025-06-06T20:35:01.000Z",
      "updated_at": "2025-06-09T05:46:56.000Z",
      "deleted_at": "2025-06-06T17:33:31.000Z"
    }
  }
}

Example Login Request

curl -X POST https://k2-ussd-api.devlorde.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Next Steps

After successful login, you'll need to:

1. Generate Service Unique ID - Create a Service ID for API requests
2. Handle Errors - Understand error responses

Getting Your Credentials

To obtain login credentials for the K2 Telecom USSD API:

1. Contact K2 Telecom: Reach out to our support team
2. Provide Business Information: Share your business details and use case
3. Review Process: We'll review your application
4. Receive Credentials: Once approved, you'll receive your username and password

Security Best Practices

• Keep your password secure: Never expose it in client-side code
• Use environment variables: Store credentials securely in your application
• Rotate passwords regularly: Update your password periodically
• Monitor usage: Regularly check your API usage and logs
• HTTPS only: Always use HTTPS for API requests
• Token expiration: JWT tokens have expiration times

Error Responses

401 Unauthorized

{
  "status": 401,
  "message": "Invalid credentials",
  "data": null
}

400 Bad Request

{
  "status": 400,
  "message": "Username and password are required",
  "data": null
}

403 Forbidden

{
  "status": 403,
  "message": "Account disabled or expired",
  "data": null
}

Rate Limiting

API requests are subject to rate limiting:

• 100 requests per minute per user
• 1000 requests per hour per user

When rate limited, you'll receive a 429 status code:

{
  "status": 429,
  "message": "Rate limit exceeded",
  "data": null
}