Get SDK Token

Generate an authentication token for the SDK using user and organization details.

POST /api/sdk/token/

Generate SDK Token

cURL

curl --request POST \
  --url https://{env}.tartanhq.com/api/sdk/token/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "[e-mail]",
  "org_name": "<string>",
  "fullname": "<string>",
  "remote_org_id": "<string>",
  "corporate_reference_data": {
    "unique_id": "<string>"
  },
  "data_model_flags": {
    "detail_info_fields": {},
    "dependent_details_fields": {},
    "ctc_details_fields": {}
  }
}
'

200

{
  "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.

Parameter	Description
api_key	Authentication key issued by Tartan. Note: This key is secret and should be kept safe.
email	The email of your corporate whose data you wish to retrieve.
org_name	The corporate’s organisation name.
fullname	The 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.

Show child attributes

data_model_flags · object

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

Show child attributes

Response

200

application/json

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

Show child attributes