Get SDK Token - Tartan

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": {},
    "dependent_details_fields": {},
    "ctc_details_fields": {}
  }
}
'

import requests

url = "https://{env}.tartanhq.com/api/sdk/token/"

payload = {
    "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": {},
        "dependent_details_fields": {},
        "ctc_details_fields": {}
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: {}, dependent_details_fields: {}, ctc_details_fields: {}}
  })
};

fetch('https://{env}.tartanhq.com/api/sdk/token/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{env}.tartanhq.com/api/sdk/token/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
                
        ],
        'dependent_details_fields' => [
                
        ],
        'ctc_details_fields' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{env}.tartanhq.com/api/sdk/token/"

	payload := strings.NewReader("{\n  \"email\": \"jsmith@example.com\",\n  \"org_name\": \"<string>\",\n  \"fullname\": \"<string>\",\n  \"remote_org_id\": \"<string>\",\n  \"corporate_reference_data\": {\n    \"unique_id\": \"<string>\"\n  },\n  \"data_model_flags\": {\n    \"detail_info_fields\": {},\n    \"dependent_details_fields\": {},\n    \"ctc_details_fields\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{env}.tartanhq.com/api/sdk/token/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jsmith@example.com\",\n  \"org_name\": \"<string>\",\n  \"fullname\": \"<string>\",\n  \"remote_org_id\": \"<string>\",\n  \"corporate_reference_data\": {\n    \"unique_id\": \"<string>\"\n  },\n  \"data_model_flags\": {\n    \"detail_info_fields\": {},\n    \"dependent_details_fields\": {},\n    \"ctc_details_fields\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{env}.tartanhq.com/api/sdk/token/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"jsmith@example.com\",\n  \"org_name\": \"<string>\",\n  \"fullname\": \"<string>\",\n  \"remote_org_id\": \"<string>\",\n  \"corporate_reference_data\": {\n    \"unique_id\": \"<string>\"\n  },\n  \"data_model_flags\": {\n    \"detail_info_fields\": {},\n    \"dependent_details_fields\": {},\n    \"ctc_details_fields\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "org_id": "a2e93895-c07d-417c-bd29-5b66cd7f4f12",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "exp": 3600,
  "corporate_reference_data": {
    "unique_id": "abc"
  }
}

{
  "code": 400,
  "message": "Invalid Email Passed!",
  "data": "<string>"
}

{
  "requestId": "33df99c9-eb6b-4d69-8d84-e73121278ee5",
  "message": "Authentication credentials were not provided.",
  "data": "<string>"
}

{
  "requestId": "56c1db80-261f-4dc4-983a-2836a2fca024",
  "message": "Internal Server Error",
  "data": "<string>"
}

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": {},
    "dependent_details_fields": {},
    "ctc_details_fields": {}
  }
}
'

import requests

url = "https://{env}.tartanhq.com/api/sdk/token/"

payload = {
    "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": {},
        "dependent_details_fields": {},
        "ctc_details_fields": {}
    }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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: {}, dependent_details_fields: {}, ctc_details_fields: {}}
  })
};

fetch('https://{env}.tartanhq.com/api/sdk/token/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{env}.tartanhq.com/api/sdk/token/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
                
        ],
        'dependent_details_fields' => [
                
        ],
        'ctc_details_fields' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{env}.tartanhq.com/api/sdk/token/"

	payload := strings.NewReader("{\n  \"email\": \"jsmith@example.com\",\n  \"org_name\": \"<string>\",\n  \"fullname\": \"<string>\",\n  \"remote_org_id\": \"<string>\",\n  \"corporate_reference_data\": {\n    \"unique_id\": \"<string>\"\n  },\n  \"data_model_flags\": {\n    \"detail_info_fields\": {},\n    \"dependent_details_fields\": {},\n    \"ctc_details_fields\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{env}.tartanhq.com/api/sdk/token/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"jsmith@example.com\",\n  \"org_name\": \"<string>\",\n  \"fullname\": \"<string>\",\n  \"remote_org_id\": \"<string>\",\n  \"corporate_reference_data\": {\n    \"unique_id\": \"<string>\"\n  },\n  \"data_model_flags\": {\n    \"detail_info_fields\": {},\n    \"dependent_details_fields\": {},\n    \"ctc_details_fields\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{env}.tartanhq.com/api/sdk/token/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"jsmith@example.com\",\n  \"org_name\": \"<string>\",\n  \"fullname\": \"<string>\",\n  \"remote_org_id\": \"<string>\",\n  \"corporate_reference_data\": {\n    \"unique_id\": \"<string>\"\n  },\n  \"data_model_flags\": {\n    \"detail_info_fields\": {},\n    \"dependent_details_fields\": {},\n    \"ctc_details_fields\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "org_id": "a2e93895-c07d-417c-bd29-5b66cd7f4f12",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "exp": 3600,
  "corporate_reference_data": {
    "unique_id": "abc"
  }
}

{
  "code": 400,
  "message": "Invalid Email Passed!",
  "data": "<string>"
}

{
  "requestId": "33df99c9-eb6b-4d69-8d84-e73121278ee5",
  "message": "Authentication credentials were not provided.",
  "data": "<string>"
}

{
  "requestId": "56c1db80-261f-4dc4-983a-2836a2fca024",
  "message": "Internal Server Error",
  "data": "<string>"
}

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

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

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

Update Employee Details Get Data Model Flags

​Generate SDK Token API: Decision Matrix

​Data Model Flags

​Structure

​Field Categories

​Flag Values

Authorizations

Body

Response

Generate SDK Token API: Decision Matrix

Data Model Flags

Structure

Field Categories

Flag Values