> 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/token-service/faq-token-service.md).

# FAQ Token Service

Frequently asked questions on Sahamati’s Token Service, covering token types, token generation, rate limits, error responses and Entity Secret rotation.

**Q: What is the Token Service (IAM)?**\
Sahamati's Token Service issues short-lived JWT access tokens. Its APIs include token generation and secret management.

**Q: Is the Token Generation API the same as the IAM API?**\
Yes. The Token Generation APIs are the same as the IAM (Token Service) APIs. In this document, we will refer to these APIs as the Token Service APIs. They include the following APIs:

* User Access Token Generation
* Entity Token Generation
* Secret Read
* Secret Reset

**Q: What are the primary types of tokens available?**\
There are two types of tokens

* User Access Token: Generated using email ID and password; used in secret management APIs.
* Entity Access Token: Generated using Secret and Entity ID; used in AA Ecosystem APIs published by ReBIT.

**Q: What are the validity periods for each token type?**\
User Access Token: 180 days. Entity Access Token: 24 hours.

**Q: What happens when the secret expires?**\
The Entity Token Generation API (Token Service) no longer accepts the expired secret, except when the *OldSecretValidity* parameter is set to a non-zero value in the next Secret Reset API call (Secret Transition). The new secret is to be used for generating Entity tokens. However, the old secret can be used for generating Entity tokens for *OldSecretValidity* days if it was set.

**Q: Who is responsible for managing the Entity Secret for Entity Token issuance in RE's organization?**\
The AA Program SPOC from RE's organization manages the Secret with the help of the Secret Read and Reset APIs provided by Sahamati <https://membersuccess.sahamati.org.in/member-services/cr-onboarding-guide/spoc-roles-and-responsibilities>

**Q: Will the existing/active tokens be revoked or invalidated when the associated secret is rotated?**\
Yes, existing/active entity tokens will remain valid until their expiry. An Entity token is valid for 24 hours.

**Q: What are the expected HTTP status code and response body/error response returned in the following scenarios?**

<table><thead><tr><th width="199.6666259765625">API Name</th><th width="192">Scenario</th><th>HTTP Status Code</th><th>HTTP Status Message</th></tr></thead><tbody><tr><td>Central Registry:<br>• Get Entities by Type API<br>• Get Entity by Type and ID API</td><td>• Expired Entity Access Token<br>• Invalid Entity Access Token</td><td>401</td><td>Unauthorized or Invalid Token</td></tr><tr><td>Token Service:<br>Generate Entity Access Token API</td><td>• Expired or Invalid Secret<br>• Invalid Entity ID</td><td>401</td><td>Unauthorized</td></tr><tr><td>• Generate Entity Access Token API<br>• Generate User Access Token API<br>• Entity Secret Read API<br>• Entity Secret Reset API<br>• CR - Get Entities by Type API<br>• CR - Get Entity by Type and ID API<br>• Saans Push API</td><td>Whenever the corresponding configured API request rate limit threshold has been exceeded for these specific APIs</td><td>429</td><td>HTTP Too Many Requests</td></tr></tbody></table>

For further details, kindly refer <https://developer.sahamati.org.in/token-service/apis>

### Entity Token Generation

**Q: What are the prerequisites for generating a User Access Token?**\
The AA Program SPOC's registered email and the password configured at Entity Onboarding (see <https://membersuccess.sahamati.org.in/member-services/cr-onboarding-guide/what-happens-after-cr-onboarding>), called from your registered IPs.

**Q: Provide a complete cURL example for User Token generation**\
Kindly refer to the section ***Generate User Access Token API*** in the link <https://developer.sahamati.org.in/token-service/apis>

**Q: What are the prerequisites for generating an Entity Access Token?**\
Your Entity ID and your current Entity Secret: the one issued at Central Registry onboarding, or the latest one you generated through rotation

**Q: Provide a complete cURL example for Entity Token generation**\
Kindly refer to the section ***Generate Entity Access Token API*** in the link <https://developer.sahamati.org.in/token-service/apis>

**Q: What does a typical entity token response include?**\
Kindly refer to the section ***Generate Entity Access Token API*** in the link <https://developer.sahamati.org.in/token-service/apis>

**Q: How should I implement entity token expiration handling in my application?**\
Fetch a new entity token before the *expiresIn* parameter value elapses (e.g., every 24 hours for entity tokens).

**Q: Can I use Postman for token testing?**\
Yes. A Postman collection is available at <https://developer.sahamati.org.in/how-to-guides/token-service-apis-production>.

**Q: Is there any rate limit enforced for the API?**\
Yes, API request rate limits have been configured for the APIs below; whenever these limits are exceeded, an ***HTTP 429 Too Many Requests*** will be returned as part of HTTP response for the API request.

| API Description         | Current rate limits (per 24 hours) |
| ----------------------- | ---------------------------------- |
| Entity Token Generation | 300                                |
| User Token Generation   | 300                                |
| Entity Secret Read      | 300                                |
| Entity Secret Reset     | 5                                  |

**Q: What error codes might I encounter during token generation?**\
Kindly refer to the section ***Generate Entity Access Token API*** in the link <https://developer.sahamati.org.in/token-service/apis>

## Entity Secret Rotation

**Q: Is the Client Secret the same as the Entity Secret? NEW**\
Yes. Both terms refer to the same secret used with your Entity ID to generate Entity Access Tokens.

**Q: What is the Entity Secret Rotation policy?**\
Entity secrets expire every 180 days and must be rotated before expiry. Secret Rotation has been mandatory since October 2024. A custom expiry duration for the Secret can be set using the optional *secretExpiryDays* parameter (not more than 180 days) in the Reset Secret API. If this *secretExpiryDays* parameter is not set, it defaults to a maximum of 180 days. The old secret will be automatically revoked once its configured validity period expires. If the *Old Secret Validity Days parameter* is set to a non-zero value but up to 7 days maximum in the Reset Secret API, the old secret will be retained until the expiry of *Old Secret Validity Days* (for supporting Secret Transition). However, as of now, the API does not provide a way to read the old secret during the secret transition after generating a new secret.

**Q: Who is responsible for secret rotation in my organization?**\
The AA Program SPOC submitted by RE to Sahamati during Entity Onboarding. To change the SPOC, kindly write to <memberservices@sahamati.org.in>.

**Q: What are the mechanisms through which I can reset the secret?**\
Kindly refer <https://developer.sahamati.org.in/how-to-guides/how-to-rotate-entity-secret>

**Q: How do I check whether my secret needs rotation?**\
2 options available

* Log in to <https://data.sahamati.org.in/self-service/check-secret-status> with your Entity ID and secret to see its expiry date.
* Via the Read Secret API. Kindly refer to the section ***Read Secret API*** *in this link* <https://developer.sahamati.org.in/token-service/apis>

**Q: Can the secret APIs be called from any network?**\
No. They must be called from your entity's network IPs registered (whitelisted during onboarding) with Sahamati.

**Q: What should I do before resetting the secret?**\
Ensure your technical team is ready to deploy the new secret immediately after the reset. If *Old Secret Validity Days (for supporting secret transition)* is set to 0, the old secret expires immediately; otherwise, update the new secret across all systems before the Old *Secret Validity Days* period ends.

**Q: Can I specify a custom validity period for the new secret?**\
Yes, via the optional *secretExpiryDays* parameter (not more than 180 days). If this parameter is not set, it defaults to a maximum of 180 days.

**Q: What is the response format for a successful secret reset?**\
Kindly refer to the section ***Reset Secret API*** in the link <https://developer.sahamati.org.in/token-service/apis>

**Q: Will my old secrets be automatically revoked?**\
Yes. The old secret will be automatically revoked once its configured validity period expires. If the *Old Secret Validity Days parameter* is set to a non-zero value but up to 7 days maximum in the Reset Secret API, the old secret will be retained until the expiry of *Old Secret Validity Days*. However, the API does not currently provide a way to read the old secret during the secret transition after generating a new secret.

**Q: What happens if I don't rotate my secret before expiration?**\
The Entity token generation API would return HTTP status 401 Unauthorized when the expired secret is used to generate entity tokens. So, it is highly recommended to rotate the secret well before it expires.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.sahamati.org.in/token-service/faq-token-service.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.