> For the complete documentation index, see [llms.txt](https://developer.sahamati.org.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.sahamati.org.in/how-to-guides/token-service-apis-production.md). # Token Service APIs - Production 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.

Token Generation use case diagram

Below are the Base URL of each environment to use IAM APIs.
EnvironmentBase URL
Productionhttps://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 > 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.
```json {"openapi":"3.0.0","info":{"title":"Token Service APIs","version":"2.1.0"},"tags":[{"name":"User APIs"}],"servers":[{"url":"https://api.sahamati.org.in/iam/v1"}],"paths":{"/user/token/generate":{"post":{"tags":["User APIs"],"summary":"Generate User Access Token API","description":"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.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"User email."},"password":{"type":"string","description":"The password associated with the user."}},"required":["username","password"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}}}}}},"components":{"schemas":{"TokenResponse":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"accessToken":{"type":"string"},"expiresIn":{"type":"integer"},"tokenType":{"type":"string"}}}}}} ``` ## Read Secret API > The Read Secret API enables admin to retrieve the current secret for a specific member. To access this information, a user access token with administrative rights must be provided. Below is the API specification.
```json {"openapi":"3.0.0","info":{"title":"Token Service APIs","version":"2.1.0"},"tags":[{"name":"Entity APIs"}],"servers":[{"url":"https://api.sahamati.org.in/iam/v1"}],"paths":{"/entity/secret/read":{"post":{"tags":["Entity APIs"],"summary":"Read Secret API","description":"The Read Secret API enables admin to retrieve the current secret for a specific member. To access this information, a user access token with administrative rights must be provided. Below is the API specification.\n","parameters":[{"name":"Authorization","in":"header","required":true,"description":"User Bearer token for authorization","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySecretReadRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySecretReadResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}}}}}},"components":{"schemas":{"EntitySecretReadRequest":{"type":"object","required":["entityId"],"properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"entityId":{"type":"string"}}},"EntitySecretReadResponse":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"entityId":{"type":"string"},"secret":{"type":"string"},"expiresOn":{"type":"number"},"expirationDate":{"type":"string"},"oldSecretValidity":{"type":"number"},"oldSecretExpirationDate":{"type":"string"}}}}}} ``` ## Reset Secret API > The Reset Secret API is used to reset the entity’s secret. To perform this action, a user access token with administrative privileges must be provided. Once reset, the generated secret will have a validity period (default and max value of 180 days) as specified in the request payload. The SPOC will have to ensure that it is renewed well before the expiry.\ > An entity’s secret can be reset up to 5 times per day. There will be a waiting period of 5 mins applied after each reset API call.\ > Below is the API specification.
```json {"openapi":"3.0.0","info":{"title":"Token Service APIs","version":"2.1.0"},"tags":[{"name":"Entity APIs"}],"servers":[{"url":"https://api.sahamati.org.in/iam/v1"}],"paths":{"/entity/secret/reset":{"post":{"tags":["Entity APIs"],"summary":"Reset Secret API","description":"The Reset Secret API is used to reset the entity’s secret. To perform this action, a user access token with administrative privileges must be provided. Once reset, the generated secret will have a validity period (default and max value of 180 days) as specified in the request payload. The SPOC will have to ensure that it is renewed well before the expiry.\nAn entity’s secret can be reset up to 5 times per day. There will be a waiting period of 5 mins applied after each reset API call.\nBelow is the API specification.\n","parameters":[{"name":"Authorization","in":"header","required":true,"description":"User Bearer token for authorization","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySecretResetRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySecretResetResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}}}}}},"components":{"schemas":{"EntitySecretResetRequest":{"type":"object","required":["entityId"],"properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"entityId":{"type":"string"},"secretExpiryDays":{"type":"integer","description":"Specifies the number of days before the secret expires. This field is optional; if not provided, a default value will be used."},"oldSecretValidity":{"type":"integer","description":"Specifies the number of days (a max of 7) for which the previous secret remains valid. The old and new secret, both, can be used to generate token during this period. This field is optional. If not provided or set to 0, the old secret will be invalidated immediately. We advise the REs to use this judiciously."}}},"EntitySecretResetResponse":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"entityId":{"type":"string"},"secret":{"type":"string"},"expiresOn":{"type":"number"},"expirationDate":{"type":"string"},"oldSecretValidity":{"type":"number"}}}}}} ``` ## Generate Entity Access Token API > 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.
```json {"openapi":"3.0.0","info":{"title":"Token Service APIs","version":"2.1.0"},"tags":[{"name":"Entity APIs"}],"servers":[{"url":"https://api.sahamati.org.in/iam/v1"}],"paths":{"/entity/token/generate":{"post":{"tags":["Entity APIs"],"summary":"Generate Entity Access Token API","description":"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.\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The entity ID."},"secret":{"type":"string","description":"The secret associated with the entity."}},"required":["id","secret"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"errorCode":{"type":"string"},"errorMsg":{"type":"string"}}}}}}}}}},"components":{"schemas":{"TokenResponse":{"type":"object","properties":{"ver":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"txnId":{"type":"string"},"accessToken":{"type":"string"},"expiresIn":{"type":"integer"},"tokenType":{"type":"string"}}}}}} ``` ## Token Generation APIs: #### API Postman Collection: {% hint style="info" %} We recommend you to use below postman collection to try out our Token-Service\[IAM] APIs {% endhint %} {% file src="/files/LrPZkvetWRM9Un9XGz41" %} ## Member Secret Management APIs #### API Collection: {% file src="/files/nymDUvFE3Ay3pAtIgcs4" %} Token-Service\[IAM] - API Collection {% endfile %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.sahamati.org.in/how-to-guides/token-service-apis-production.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.