> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersync.tartanhq.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get SDK Token
> Generate an authentication token for the SDK using user and organization details.
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](/docs/hrmssync/sdk) 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
```json theme={"dark"}
{
"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
## OpenAPI
````yaml POST /api/sdk/token/
openapi: 3.0.0
info:
title: Employee List API
description: Retrieve a paginated list of employees from the organization.
version: 1.0.0
servers:
- url: https://{env}.tartanhq.com
description: Dynamic environment-based server
variables:
env:
default: dev
security: []
paths:
/api/sdk/token/:
post:
summary: Generate SDK Token
description: >-
Issues an SDK authentication token using email, organization name, full
name, and remote organization ID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- org_name
- fullname
properties:
email:
type: string
format: email
description: The user's email address.
org_name:
type: string
description: The name of the organization.
fullname:
type: string
description: The user's full name.
remote_org_id:
type: string
description: A unique identifier for the remote organization.
corporate_reference_data:
type: object
description: Additional reference data for the corporate organization.
properties:
unique_id:
type: string
description: Custom unique identifier for the corporate.
data_model_flags:
type: object
description: >-
Configuration flags to control which data fields are
enabled/disabled in the SDK.
properties:
detail_info_fields:
type: object
properties:
gender:
type: integer
enum:
- -1
- 0
- 1
description: >-
Gender field flag (-1=required, 0=optional,
1=enabled optional)
dob:
type: integer
enum:
- -1
- 0
- 1
description: >-
Date of birth field flag (-1=required, 0=optional,
1=enabled optional)
dependent_details_fields:
type: object
properties:
dependentDetails_mobileNumber:
type: integer
enum:
- -1
- 0
- 1
description: >-
Dependent mobile number field flag (-1=required,
0=optional, 1=enabled optional)
ctc_details_fields:
type: object
properties:
ctc_deductions_misc:
type: integer
enum:
- -1
- 0
- 1
description: >-
CTC miscellaneous deductions field flag
(-1=required, 0=optional, 1=enabled optional)
ctc_deductions_esi:
type: integer
enum:
- -1
- 0
- 1
description: >-
CTC ESI deductions field flag (-1=required,
0=optional, 1=enabled optional)
responses:
'200':
description: Successful token generation
content:
application/json:
schema:
type: object
properties:
org_id:
type: string
format: uuid
example: a2e93895-c07d-417c-bd29-5b66cd7f4f12
access_token:
type: string
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
exp:
type: integer
example: 3600
corporate_reference_data:
type: object
properties:
unique_id:
type: string
example: abc
'400':
description: Invalid email provided
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 400
message:
type: string
example: Invalid Email Passed!
data:
type: string
nullable: true
'401':
description: Authentication credentials missing
content:
application/json:
schema:
type: object
properties:
requestId:
type: string
format: uuid
example: 33df99c9-eb6b-4d69-8d84-e73121278ee5
message:
type: string
example: Authentication credentials were not provided.
data:
type: string
nullable: true
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
requestId:
type: string
format: uuid
example: 56c1db80-261f-4dc4-983a-2836a2fca024
message:
type: string
example: Internal Server Error
data:
type: string
nullable: true
security:
- TokenAuth: []
components:
securitySchemes:
TokenAuth:
type: apiKey
in: header
name: Authorization
````