Token Service APIs - Production

Identity and Access Management ( Token Service) APIs

Each member of the Sahamati Network will be onboarded with a designated user who holds an admin role to manage the entity’s profile and secret.

During the onboarding process, the designated user will receive an email containing a verification link. After email verification, the user will be prompted to set a password, completing the account activation process.
Once the password is set, the user can generate the User Access Token by providing their email and the new password. This token is used for authenticating the entity’s secrets.
The designated user can then use the User Access Token to access the entity’s secret and, if necessary, reset the secret.
Finally, the entity secret is used to generate the Entity Access Token, which is needed for interactions with the ReBIT APIs within the AA network.

Entity Token Generation use case

The Regulated Entities (REs) should generate the Access Token using the Token API from Sahamati for accessing and authentication of any APIs in the AA ecosystem including Sahamati APIs.

Here is the sequence diagram for the Token Generation Process.

Below are the Base URL of each environment to use IAM APIs.

Environment

Base URL

Production

https://api.sahamati.org.in/iam

Please note that the following documentation displays the Base URLs from the Production environment. Ensure you use the appropriate Base URLs depending on the environment you are working in.

Generate User Access Token API

post

To generate a User Access Token, the user must provide their username (email) and the password configured during the account activation process. This access token is necessary for interacting with the member's secret management APIs. The access token has an expiry of 180 days. Below is the API specification.

Body

usernamestringRequired

User email.

passwordstringRequired

The password associated with the user.

Responses

200

Successful response

application/json

verstringOptionalExample: 1.0.0

timestampstring · date-timeOptionalExample: 2024-07-16T11:33:34.509Z

txnIdstringOptionalExample: f35761ac-4a18-11e8-96ff-0277a9fbfedc

accessTokenstringOptional

expiresInintegerOptionalExample: 86400

tokenTypestringOptionalExample: Bearer

400

Bad Request

application/json

401

Unauthorized

application/json

post

/user/token/generate

Curl

curl -L \
  -X POST \
  'https://api.sahamati.org.in/iam/v1/user/token/generate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=<email>&password=<password>

{
  "ver": "1.0.0",
  "timestamp": "2024-07-16T11:33:34.509Z",
  "txnId": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "accessToken": "",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}

Read Secret API

post

The Read Secret API enables admin to retrieve the current secret for a specific member. To access this information, an user access token with administrative rights must be provided. Below is the API specification.

Header parameters

AuthorizationstringRequired

User Bearer token for authorization

Body

verstringRequiredExample: 1.0.0

timestampstring · date-timeRequiredExample: 2024-07-16T11:33:34.509Z

txnIdstringRequiredExample: f35761ac-4a18-11e8-96ff-0277a9fbfedc

entityIdstringRequiredExample: aa-1

secretExpiryDaysintegerOptional

Specifies the number of days before the secret expires. This field is optional; if not provided, a default value will be used.

Example: 100

Responses

200

Successful response

application/json

verstringOptionalExample: 1.0.0

timestampstring · date-timeOptionalExample: 2024-07-16T11:33:34.509Z

txnIdstringOptionalExample: f35761ac-4a18-11e8-96ff-0277a9fbfedc

entityIdstringOptionalExample: aa-1

secretstringOptionalExample: xxxxxxxxxxxxxxxxxxxxx

expiresOnnumberOptionalExample: 1725010763

expirationDatestringOptionalExample: 2024-12-17T07:10:52.929

400

Bad Request

application/json

401

Unauthorized

application/json

post

/entity/secret/read

POST /iam/v1/entity/secret/read HTTP/1.1
Host: api.sahamati.org.in
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "ver": "1.0.0",
  "timestamp": "2024-07-16T11:33:34.509Z",
  "txnId": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "entityId": "aa-1",
  "secretExpiryDays": 100
}

{
  "ver": "1.0.0",
  "timestamp": "2024-07-16T11:33:34.509Z",
  "txnId": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "entityId": "aa-1",
  "secret": "xxxxxxxxxxxxxxxxxxxxx",
  "expiresOn": 1725010763,
  "expirationDate": "2024-12-17T07:10:52.929"
}

Reset Secret API

post

The Reset Secret API is designed to allow an admin to reset a member's secret. To perform this action, an access token with administrative privileges for the specified member is required. Once reset, the newly generated secret will have a validity period of 180 days by default, after which it will need to be renewed or reset again.

With the latest enhancements, members can now select their desired validity period for secrets, up to a defined maximum limit (default: 180 days). The specified validity period is compared with the admin access token expiry, and the minimum value is applied to ensure authentication and security. Additionally, a grace period of 5 days is provided to facilitate a seamless transition between old and new secrets.

Below is the API specification.

Header parameters

AuthorizationstringRequired

User Bearer token for authorization

Body

verstringRequiredExample: 1.0.0

timestampstring · date-timeRequiredExample: 2024-07-16T11:33:34.509Z

txnIdstringRequiredExample: f35761ac-4a18-11e8-96ff-0277a9fbfedc

entityIdstringRequiredExample: aa-1

secretExpiryDaysintegerOptional

Specifies the number of days before the secret expires. This field is optional; if not provided, a default value will be used.

Example: 100

Responses

200

Successful response

application/json

verstringOptionalExample: 1.0.0

timestampstring · date-timeOptionalExample: 2024-07-16T11:33:34.509Z

txnIdstringOptionalExample: f35761ac-4a18-11e8-96ff-0277a9fbfedc

entityIdstringOptionalExample: aa-1

secretstringOptionalExample: xxxxxxxxxxxxxxxxxxxxx

expiresOnnumberOptionalExample: 1725010763

expirationDatestringOptionalExample: 2024-12-17T07:10:52.929

400

Bad Request

application/json

401

Unauthorized

application/json

post

/entity/secret/reset

POST /iam/v1/entity/secret/reset HTTP/1.1
Host: api.sahamati.org.in
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "ver": "1.0.0",
  "timestamp": "2024-07-16T11:33:34.509Z",
  "txnId": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "entityId": "aa-1",
  "secretExpiryDays": 100
}

{
  "ver": "1.0.0",
  "timestamp": "2024-07-16T11:33:34.509Z",
  "txnId": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "entityId": "aa-1",
  "secret": "xxxxxxxxxxxxxxxxxxxxx",
  "expiresOn": 1725010763,
  "expirationDate": "2024-12-17T07:10:52.929"
}

Generate Entity Access Token API

post

To generate a Member (Entity) Access Token, the client ID and Secret are required. The API generates the token with a warning if the secret is within the grace period, but it will fail once the grace period has ended. This token is used for interactions with other members and has a validity of 24 hours. The API specification is detailed below.

Body

idstringRequired

The entity ID.

secretstringRequired

The secret associated with the entity.

Responses

200

Successful response

application/json

verstringOptionalExample: 1.0.0

timestampstring · date-timeOptionalExample: 2024-07-16T11:33:34.509Z

txnIdstringOptionalExample: f35761ac-4a18-11e8-96ff-0277a9fbfedc

accessTokenstringOptional

expiresInintegerOptionalExample: 86400

tokenTypestringOptionalExample: Bearer

400

Bad Request

application/json

401

Unauthorized

application/json

post

/entity/token/generate

Curl

curl -L \
  -X POST \
  'https://api.sahamati.org.in/iam/v1/entity/token/generate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'id=<id>&secret=<secret>

{
  "ver": "1.0.0",
  "timestamp": "2024-07-16T11:33:34.509Z",
  "txnId": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}

Token Generation APIs:

API Postman Collection:

We recommend you to use below postman collection to try out our Token-Service[IAM] APIs

4KB

IAM-Service[Token].postman_collection.json

Open

Member Secret Management APIs

API Collection:

PreviousHow to Rotate Entity Secret

Last updated 4 days ago

Was this helpful?

hashtagEntity Token Generation use case

hashtagGenerate User Access Token API

hashtagRead Secret API

hashtagReset Secret API

hashtagGenerate Entity Access Token API

hashtagToken Generation APIs:

hashtagAPI Postman Collection:

hashtagMember Secret Management APIs

hashtagAPI Collection:

Entity Token Generation use case

Generate User Access Token API

Read Secret API

Reset Secret API

Generate Entity Access Token API

Token Generation APIs:

API Postman Collection:

Member Secret Management APIs

API Collection: