Session Management

Before using any of our SDKs (Android, Web, or iOS), you need to obtain a session ID. This guide explains how to generate and manage session IDs.

Important Note: The GetSessionId endpoint serves dual functionality - it creates a new customer profile if one doesn't exist with the provided email address, or continues the onboarding journey for existing customers. The customer email serves as the unique identifier in the system.

Getting a Session ID

Make a POST request to our session management endpoint:

POST {auth_base_url}/api/AppSessionManager/GetSessionId

Request Headers

Content-Type: application/json

Request Body

For Individual Customer:

{
  "appId": "your-app-id",
  "appSecret": "your-app-secret",
  "tenantId": "your-tenant-id",
  "formId": "your-form-id",
  "customerType": "Individual",
  "customerEmail": "customer@example.com",
  "customerMobileNumber": "+971500000000", // Optional
  "individual": {
    "firstName": "John",
    "lastName": "Doe"
  }
}

For Legal Entity Customer:

{
  "appId": "your-app-id",
  "appSecret": "your-app-secret",
  "tenantId": "your-tenant-id",
  "formId": "your-form-id",
  "customerType": "LegalEntity",
  "customerEmail": "business@example.com",
  "customerMobileNumber": "+971500000000", // Optional
  "company": {
    "fullName": "Company Name Ltd",
    "registrationNumber": "12345",
    "tradingName": "Trading Name"
  }
}

Required Parameters

Parameter	Type	Required	Description
appId	string	Yes	Your application ID
appSecret	string	Yes	Your application secret
tenantId	string	Yes	Your tenant ID
formId	string	Yes	The form ID for KYC
customerType	string	Yes	Type of customer ("Individual" or "LegalEntity")
customerEmail	string	Yes	Customer's email address
individual	object	Conditional	Required when customerType is "Individual"
company	object	Conditional	Required when customerType is "LegalEntity"

Individual Object Parameters

Parameter	Type	Required	Description
firstName	string	Yes	Customer's first name
lastName	string	Yes	Customer's last name

Company Object Parameters

Parameter	Type	Required	Description
fullName	string	Yes	Company's full legal name
registrationNumber	string	Yes	Company's registration number
tradingName	string	Yes	Company's trading name

Optional Parameters

Parameter	Type	Required	Description
customerMobileNumber	string	No	Customer's mobile number

Response

{
  "version": null,
  "statusCode": 200,
  "messages": [
    "Processed successfully"
  ],
  "result": {
    "sessionId": "ab98babe-b555-4b79-88bf-967f454df0c0"
  }
}

Validation Rules

1. Either individual or company must be provided (not both, not neither)
2. The customerType must match the provided customer details object:
   • When customerType is "Individual", the individual object must be provided
   • When customerType is "LegalEntity", the company object must be provided
3. The customerType must be a valid enum value ("Individual" or "LegalEntity")
4. AppId and AppSecret must be valid and non-empty

Code Examples

JavaScript/TypeScript

// For Individual Customer
async function getIndividualSessionId(customerData) {
  const response = await fetch(`${auth_base_url}/api/AppSessionManager/GetSessionId`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      appId: 'your-app-id',
      appSecret: 'your-app-secret',
      tenantId: 'your-tenant-id',
      formId: 'your-form-id',
      customerType: 'Individual',
      customerEmail: customerData.email,
      customerMobileNumber: customerData.mobileNumber, // Optional
      individual: {
        firstName: customerData.firstName,
        lastName: customerData.lastName
      }
    })
  });

  const data = await response.json();
  return data.result.sessionId;
}

// For Legal Entity Customer
async function getLegalEntitySessionId(companyData) {
  const response = await fetch(`${auth_base_url}/api/AppSessionManager/GetSessionId`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      appId: 'your-app-id',
      appSecret: 'your-app-secret',
      tenantId: 'your-tenant-id',
      formId: 'your-form-id',
      customerType: 'LegalEntity',
      customerEmail: companyData.email,
      customerMobileNumber: companyData.mobileNumber, // Optional
      company: {
        fullName: companyData.fullName,
        registrationNumber: companyData.registrationNumber,
        tradingName: companyData.tradingName
      }
    })
  });

  const data = await response.json();
  return data.result.sessionId;
}

Error Handling

The API may return these error codes:

Status Code	Description	Solution
400	Invalid request parameters	Check request body format
400	"Invalid Request"	Ensure request body is not null
400	"Invalid AppId or AppSecret"	Verify appId and appSecret values
400	"Invalid Customer Details"	Ensure either individual or company object is provided
400	"Invalid Customer Type"	Ensure customerType matches the provided data object
400	"Invalid customer type."	Ensure customerType is either "Individual" or "LegalEntity"
401	Invalid credentials	Verify appId and appSecret
403	Unauthorized tenant	Check tenantId
429	Too many requests	Implement rate limiting
500	Server error	Retry with exponential backoff

Best Practices

1. Security

   • Safeguard appId and appSecret credentials by restricting exposure in client-side code
   • Establish a secure backend service to generate and manage session IDs
   • Implement comprehensive error handling with appropriate logging

2. Performance

   • Strategically cache session IDs according to your application workflow
   • Implement exponential backoff retry logic for transient failures
   • Establish appropriate network timeout thresholds with fallback mechanisms

3. Implementation

   • Generate a unique session ID for each distinct KYC process
   • Implement proper session lifecycle management to prevent use of expired sessions
   • Consider the email's role as a unique identifier when managing customer data