How to Rotate Entity Secret

This is to inform all participants in the Account Aggregator (AA) ecosystem about the Client Secret Rotation policy that has been in existence since October 2024. The participants are mandated to implement this policy.

Key Updates

• Best Practice Recommendation: Following feedback from market participants, it was recommended that the Client Secret used for authentication on Token Service should be rotated periodically to enhance security and mitigate risks related to token misuse or compromise.

• Current Observations: A substantial number of participants have not rotated the Client Secret provided during their initial onboarding with the Central Registry (CR). To address this, Sahamati provides a Client Secret Rotation feature that enables participants to rotate their secrets efficiently and securely.

• Designated Authorised Users: Each participant organisation must designate an authorised user who will be responsible for managing the Client Secret rotation. This user will be onboarded into the Token Service (Identity & Access Management) and tasked with rotating the secret using APIs. The SPOC (Single Point of Contact) must also ensure that the newly generated secret token is securely integrated into their organisation's systems. It is recommended to use a service account email associated with the participant organisation. This ensures the account remains under the organisation's control for long-term management, providing consistency and seamless operation over time.

• Secret Token Expiration: Client Secrets set by entities will expire every 180 days. All participants are required to rotate their Client Secrets before the expiration date to ensure uninterrupted access to the network. This regular rotation is essential to maintaining the security of the AA ecosystem.

Action Required

1. Onboard Your Designated User: The "AA program SPOC" of your entity will be the "designated user" to rotate the secret. In case you want to update the SPOC, please reach out to [email protected].

2. Generate and Rotate Client Secrets: Once the designated user is onboarded by Sahamati, they will receive an email to set a password.

   1. Step-1: Generate a User-Token

      Use the email and the newly set password to generate a user token from the Token Service through the User Token Generate API.

   2. Step-2: Read existing secret (if needed)

      Use the user-token to read the secret of your entity using the Secret - Read API

   3. Step-3: Reset the entity secret

      Use the user-token to reset the secret of your entity using the Secret - Reset API.

   4. Step-4: The new secret should be applied to your system. Please refer to the API documentation for further details.

3. Update Systems for Token Expiration: Ensure that your systems and applications are prepared to handle the periodic 24-hour token expiration. Implement a token rotation mechanism using the Entity Token Generation API to automate this process.

4. Manual Rotation Option: If automation is not yet ready, you can still rotate the token manually by directly calling Sahamati’s API.

Please ensure these changes are incorporated into your applications and processes by the given deadlines to maintain uninterrupted access to the AA ecosystem.