POST
/
api
/
sdk
/
token
/
Generate SDK Token
curl --request POST \
  --url https://{env}.tartanhq.com/api/sdk/token/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "jsmith@example.com",
  "org_name": "<string>",
  "fullname": "<string>",
  "remote_org_id": "<string>",
  "corporate_reference_data": {
    "unique_id": "<string>"
  },
  "data_model_flags": {
    "detail_info_fields": {
      "gender": -1,
      "dob": -1
    },
    "dependent_details_fields": {
      "dependentDetails_mobileNumber": -1
    },
    "ctc_details_fields": {
      "ctc_deductions_misc": -1,
      "ctc_deductions_esi": -1
    }
  }
}'
{
  "org_id": "a2e93895-c07d-417c-bd29-5b66cd7f4f12",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "exp": 3600,
  "corporate_reference_data": {
    "unique_id": "abc"
  }
}
The token generated is valid for 1 hour.
Reach out to your SPOC in Tartan for api_key.
ParameterDescription
api_keyAuthentication key issued by Tartan. Note: This key is secret and should be kept safe.
emailThe email of your corporate whose data you wish to retrieve.
org_nameThe corporate’s organisation name.
fullnameThe name of the HR admin at the corporate organisation.
remote_org_id (optional)A unique identifier that allows you to bypass validation checks for corporates with multiple domains. It ensures a consistent org_id is provided for the same organization, regardless of domain variations. This is a client-defined identifier that Tartan uses to link users to a corporate. Refer to API workflow section of this page for a detailed explanation of this API workflow.
corporate_reference_data (optional)Additional reference data for the corporate organization. Can include custom fields like unique_id or other metadata.
data_model_flags (optional)Configuration flags to control which data fields are enabled/disabled in the SDK. Contains nested objects for different field categories.

​
Generate SDK Token API: Decision Matrix

Input Validation: The API begins by validating the provided inputs ( email , org_name, fullname, and optionally remote_org_id). If any required input is missing or invalid, the API returns an error. Check for remote_org_id: If a remote_org_id is provided, the API directly maps this identifier to an existing org_id without further domain or name validation and creates a user under it using the provided email if needed. This path is designed for clients with multiple domains or custom configurations who want a consistent identifier. Domain-Based org_id Determination: If remote_org_id is not provided, the API does the following: Domain Classification: The API checks if the email domain belongs to a common domain (Refer to list attached below) or a private domain (custom domains used by corporates). Private Domain Handling: If the email belongs to a private domain, the API ensures that there is a one-to-one mapping between the private domain and an org_id. If an org_id already exists for that private domain, it is returned. Otherwise, a new org_id is created for that domain. Common/Public Domain Handling: If the email belongs to a common domain, the API cannot rely on the domain alone to determine the organization. In this case, the API checks if the provided org_name is unique Unique org_name: If the organization name is unique, a new org_id is generated. Existing org_name: If the organization name already exists, the corresponding org_id is returned. This step prevents the creation of duplicate organizations when using common/public domains. Flowchart representing the onboarding process -

​
Data Model Flags

The data_model_flags parameter allows you to control which data fields are enabled or disabled in the SDK. This gives you granular control over the data collection process.

​
Structure

{
  "data_model_flags": {
    "detail_info_fields": {
      "gender": -1,
      "dob": -1
    },
    "dependent_details_fields": {
      "dependentDetails_mobileNumber": 1
    },
    "ctc_details_fields": {
      "ctc_deductions_misc": 1,
      "ctc_deductions_esi": 1
    }
  }
}

​
Field Categories

detail_info_fields: Controls basic employee information fields
  • gender: -1 (mandatory enabled) or 1 (enabled)
  • dob: -1 (mandatory enabled) or 1 (enabled)
dependent_details_fields: Controls dependent information fields
  • dependentDetails_mobileNumber: -1 (mandatory enabled) or 1 (enabled)
ctc_details_fields: Controls CTC (Cost to Company) related fields
  • ctc_deductions_misc: -1 (mandatory enabled) or 1 (enabled)
  • ctc_deductions_esi: -1 (mandatory enabled) or 1 (enabled)

​
Flag Values

  • -1: Field is enabled and required
  • 0: Field is disabled
  • 1: Field is enabled and optional

Authorizations

​
Authorization
string
header
required

Body

application/json
​
email
string<email>
required

The user's email address.

​
org_name
string
required

The name of the organization.

​
fullname
string
required

The user's full name.

​
remote_org_id
string

A unique identifier for the remote organization.

​
corporate_reference_data
object

Additional reference data for the corporate organization.

​
data_model_flags
object

Configuration flags to control which data fields are enabled/disabled in the SDK.

Response

Successful token generation

​
org_id
string<uuid>
Example:

"a2e93895-c07d-417c-bd29-5b66cd7f4f12"

​
access_token
string
Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
exp
integer
Example:

3600

​
corporate_reference_data
object