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
  "employeeId": "assigned-employee-id", // Optional
  "clientId": "5b2a1c84-9d77-4e1a-a8b3-2f9a45d6c901", // Optional
  "sendEmail": true, // 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
  "employeeId": "assigned-employee-id", // Optional
  "clientId": "5b2a1c84-9d77-4e1a-a8b3-2f9a45d6c901", // Optional
  "sendEmail": true, // 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
employeeId	string	No	Unique identifier of the employee assigned to the customer
clientId	string	No	ID of the client the new profile should be assigned to. Must belong to your tenant and be permitted for your API key. If omitted, the profile is assigned to the tenant's default client.
sendEmail	boolean	No	Whether to send a welcome email to new customers

Response

{
  "version": null,
  "statusCode": 200,
  "messages": [
    "Processed successfully"
  ],
  "result": {
    "sessionId": "75f6b9b8-cbf0-4fa2-a814-5f14af3d2ee3",
    "expiryDate": "2026-02-05T05:47:26.7887865Z",
    "submissionId": "9ded4e5e-34b7-4e2d-81e2-d413368c920b",
    "customerId": "08241ca6-16d2-4397-9431-56e3dee76929",
    "clientId": "5b2a1c84-9d77-4e1a-a8b3-2f9a45d6c901",
    "isNewCustomer": false
  }
}

Response Fields

Field	Type	Description
sessionId	string	Unique session identifier. Pass this to the Azakaw SDKs to launch the KYC flow for this customer.
expiryDate	string (ISO 8601, UTC)	When the session expires.
submissionId	string	Identifier of the KYC submission associated with this session.
customerId	string	Identifier of the customer (individual user or company) associated with this session.
clientId	string	Identifier of the client the customer profile is assigned to. Echoes the clientId you supplied, or the tenant's default client when omitted.
isNewCustomer	boolean	true if a new customer profile was created by this call; false if an existing customer was matched by email.

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
      employeeId: customerData.employeeId, // Optional
      clientId: customerData.clientId, // Optional
      sendEmail: customerData.sendEmail, // 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
      employeeId: companyData.employeeId, // Optional
      clientId: companyData.clientId, // Optional
      sendEmail: companyData.sendEmail, // 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"
400	"Invalid Client Id"	Ensure the clientId belongs to your tenant
400	"Client Id is not permitted for this API key"	Use a clientId that your API key is permitted to assign profiles to
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

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

Invalidating a Session ID

The Logout Session API allows you to invalidate a session associated with a customer. This endpoint marks the sessionId as invalid for future token exchanges, preventing stale links or browser back-button navigation from reopening the SDK with the same session.

POST {auth_base_url}/api/AppSessionManager/InvalidateSessionId

Request Headers

Content-Type: application/json

Request Body

{
  "appId": "your-app-id",
  "appSecret": "your-app-secret",
  "tenantId": "your-tenant-id",
  "sessionId": "your-session-id"
}

Parameters

Parameter	Type	Required	Description
appId	string	Yes	Your application ID
appSecret	string	Yes	Your application secret
tenantId	string	Yes	Your tenant ID
sessionId	string	Yes	The session ID to invalidate. Must have been issued under the same AppKey making this call.

Response

{
  "version": null,
  "statusCode": 200,
  "messages": [
    "Processed successfully"
  ],
  "result": {
    "sessionId": "75f6b9b8-cbf0-4fa2-a814-5f14af3d2ee3",
    "invalidatedAt": "2026-06-16T09:31:08.4421067Z"
  }
}

Response Fields

Field	Type	Description
sessionId	string	The session ID that was invalidated. Echoes the value supplied in the request.
invalidatedAt	string (ISO 8601, UTC)	When the session was marked invalid. For sessions that were already invalidated or had naturally expired, this reflects the original time.

Code Examples

JavaScript/TypeScript

async function invalidateSessionId(sessionId) {
  const response = await fetch(`${auth_base_url}/api/AppSessionManager/InvalidateSessionId`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      appId: 'your-app-id',
      appSecret: 'your-app-secret',
      tenantId: 'your-tenant-id',
      sessionId: 'your-session-id'
    })
  });

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

Error Handling

The API may return these error codes:

Status Code	Description	Solution
400	"Invalid Request"	Ensure the request body is well-formed and not null
403	"Invalid AppCredentials"	Verify your AppCredentials
403	"Invalid TenantId"	Ensure tenantId matches the tenant your AppCredentials belong to
401	"Session does not belong to this AppKey"	The sessionId was issued under a different AppKey — call this endpoint from the same AppKey that created the session
403	"Invalid SessionId"	The provided sessionId was created using a different AppKey. Call this endpoint using the same AppKey that was used to create the session

Note: Invalidating a session immediately revokes the session and all tokens associated with it. Any active SDK sessions associated with the invalidated session are terminated, and users must initiate a new session to continue.

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