Skip to main content

Generate Service Unique ID

Overview​

After successful authentication, you need to generate a Service Unique ID that will be used for all API requests. This Service ID is valid for 1 hour and must be regenerated after expiration.

Endpoint​

URL: {{base_url}}/api/clients/generate-service-id

Method: POST

Headers:

Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Request Body: (Empty - no body required)

Response​

{
  "status": 201,
  "message": "Service created",
  "data": {
    "SERVICE_ID": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXJ2aWNlSWQiOiI3ODY0ZTg4Ni03MmYyLTRlMDYtYmZhZS0yZWJkZjdkYWEwMGEiLCJpYXQiOjE3NDk2OTcyNzEsImV4cCI6MTc0OTcwMDg3MX0.jAMYfPaeql64PbXWl0waYKX6JKqUiS8OF1ECg00C6uc"
  }
}

Example Request​

curl -X POST https://k2-ussd-api.devlorde.xyz/api/clients/generate-service-id \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json"

Using the Service ID​

After generating the Service ID, include it in the Authorization header for all subsequent API requests.

Note: Keep your Service ID secure and never expose it in client-side code or public repositories.

Important Notes​

  • Validity Period: The Service ID is valid for 1 hour (3600 seconds)
  • Regeneration Required: You must regenerate the Service ID after it expires
  • API Requests: Use this Service ID in the Authorization header for all API requests
  • Security: Keep your Service ID secure and don't expose it in client-side code

Error Responses​

401 Unauthorized​

{
  "status": 401,
  "message": "Invalid JWT token",
  "data": null
}

403 Forbidden​

{
  "status": 403,
  "message": "JWT token expired",
  "data": null
}

400 Bad Request​

{
  "status": 400,
  "message": "Invalid request format",
  "data": null
}

Best Practices​

  1. Store Service ID Securely: Use environment variables or secure storage
  2. Monitor Expiration: Track when your Service ID will expire
  3. Implement Auto-Regeneration: Automatically regenerate Service ID before expiration
  4. Error Handling: Handle Service ID expiration gracefully
  5. Logging: Log Service ID generation for debugging purposes

Implementation Example​

class K2USSDClient {
  constructor(username, password) {
    this.username = username;
    this.password = password;
    this.jwtToken = null;
    this.serviceId = null;
    this.serviceIdExpiry = null;
  }

  async login() {
    const response = await fetch('https://k2-ussd-api.devlorde.xyz/api/auth/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        username: this.username,
        password: this.password
      })
    });

    const data = await response.json();
    if (data.status === 200) {
      this.jwtToken = data.data.token;
      return data;
    } else {
      throw new Error(data.message);
    }
  }

  async generateServiceId() {
    if (!this.jwtToken) {
      throw new Error('Must login first');
    }

    const response = await fetch('https://k2-ussd-api.devlorde.xyz/api/clients/generate-service-id', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.jwtToken}`,
        'Content-Type': 'application/json'
      }
    });

    const data = await response.json();
    if (data.status === 201) {
      this.serviceId = data.data.SERVICE_ID;
      this.serviceIdExpiry = Date.now() + (60 * 60 * 1000); // 1 hour from now
      return data;
    } else {
      throw new Error(data.message);
    }
  }

  async makeApiRequest(endpoint, options = {}) {
    // Check if Service ID is expired or about to expire
    if (!this.serviceId || Date.now() >= this.serviceIdExpiry - (5 * 60 * 1000)) {
      await this.generateServiceId();
    }

    return fetch(`https://k2-ussd-api.devlorde.xyz${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.serviceId}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
  }
}

Next Steps​