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.

Do I need to rotate my secret?

1. Before proceeding with the rotation steps, please verify whether your Entity Secret requires rotation.

2. You can log in to the Check Secret Status page using your Entity ID and Entity Secret to check the current secret expiry date.

3. If your secret is nearing expiry or has expired, you should proceed with rotating the secret.

4. If rotation is required, follow the steps below to rotate the secret either through the API method or through the Portal.

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].

   Once the designated user is onboarded by Sahamati, they will receive an email to set a password.

1. Generate and Rotate Entity Secrets:

Important Note: Before proceeding with the secret reset, ensure that your technical team is informed and prepared to update and start using the new secret in the system immediately after rotation.

Rotating the Secret

There are two methods to rotate the secret. One is via the via (Method 1) and the other is using a web portal (Method 2).

Method 1: Rotate Secret Using the Portal

You can also rotate the entity secret directly through the portal.

1. Visit the Sahamati Self Service Portal

2. Click on Login to Self Service Portal.

3. Enter your Entity ID.

4. Enter the SPOC Email ID registered with the entity.

5. Enter the OTP received on the SPOC email ID.

6. Enter the SPOC Password to log in to the portal.

After logging in, navigate to the "Reset Secret" section and proceed with the Secret Rotation. Once the secret is rotated, copy the new secret from the “View Secret” section after the reset. Share the new secret with your technical team to update it in your system configuration.

Method 2: Rotate Secret Using API

Important Note: The APIs referred below must be accessed from your entity's network IPs registered with Sahamati.

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.

5. 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.

6. 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.