Self-Service API Credential Rotation on Developer Platform
At PayPal, we take security seriously. The API client ID and client secret in the API world are akin to username and password in the web world. It is a well-known security best practice to regularly change the passwords (password rotation). Similarly, in the API world, it is a security best practice to regularly rotate the API client-secret that your application uses from other API providers such as PayPal. Regularly scheduled changes to the API client-secret keep attackers at bay and ensure that your app is less vulnerable to being compromised. For the sake of simplicity, I will refer to the change of API client-secret as API credential rotation in the rest of this article.
To simplify the credential rotation process, we have enabled this capability as a self-service feature on the developer portal. We hope that this feature will provide greater flexibility to our developers in rotating credentials per their own schedule.
Lifecycle of an API client-secret at PayPal
A client-secret can have the following three statuses:
- Enabled: The client-secret can be used to authenticate your application for API integration
- Disabled: The client-secret cannot be used to authenticate your application for API integration. The client-secret can, however, be moved to “Enabled” status and made functional again.
- Deleted: The client-secret is no longer available for use. A client-secret once deleted cannot be Enabled or recovered.
There can only be a maximum of two client-secrets that can be created for each app. These client-secrets can be in either of these two states: Enabled or Disabled.
Process of rotating a client-secret
Rotating your client-secret is an easy process and can be done in a self-service fashion on the Developer Portal. The steps are detailed below and are applicable to both your Live and Sandbox client-secret rotation.
- Login to Developer Portal and access your REST App
2. Click on the App to view your API Client ID and Client Secret
3. Generate an additional client-secret credential as backup to your existing “Enabled” credential.
4. Update your web or mobile application to start using the newly generated API credential
5. Test your application and ensure that all PayPal API functionality is working fine with the newly generated credentials
6. Disable the old credential now to ensure that you have only one active credential at a given time.
7. Re-validate that your application is continuing to work even after the old REST App Credentials have been disabled, to rule out any possibility of your application using older credentials.
8. If there are any issues with your application functionality, feel free to re-enable the “Disabled” client-secret and troubleshoot the issue.
9. If validation is successful, then delete the old credential. This will ensure that the older credentials are not used by someone on your team by mistake. Once deleted the credentials cannot be recovered due to security reasons. Hence, it is critical that you ensure that your application is not dependent on these old credentials before you delete them.
Best practices for credential rotation
- Merchants and System Integrators should define, describe, document and agree on a standard process and steps for client-secret rotation. Create a standard operating procedure (SOP) on credential management and the process to follow in case of a suspected or known breach of credentials. Having a well-defined process will help prevent a panic reaction, and will allow you to gracefully handle the breach without negatively impacting your customers and business
- Unless it’s an emergency, and you are aware of a breach or bad actor, it is best to identify an appropriate day and time when your mobile app or website experiences little to no traffic, to rotate your client-secret.
- Thoroughly validate that your application is working fine with the new credentials before deleting an existing client-secret.
- Rotate client-secrets when your credential custodians (the individual or developer who manages the credentials for your organization or business) change.
- You can choose to disable a credential immediately if you suspect they have been compromised. Note, however, that your application will stop working until you create a new credential pair, change it to “Enabled” status and make changes in your application to start using the new credentials.
- It is also a good idea to put your API client ID and client-secret credentials in a configuration file instead of hard-coding in your code base. This would allow you to quickly update and deploy changes to the configuration file without having to make any code changes, and reducing the overall time to activate new credentials on your mobile app or website.
- Delete “Disabled” credentials regularly after validating your application with the new client-secret. This practice will ensure that compromised or old credentials are not enabled by mistake. Additionally, it makes the management of credentials simpler if you don’t have to scroll down a list :)
In conclusion, regularly updating the client-secret/credentials associated with your applications is a security best practice. It is suggested that developers utilize the self-service client-secret rotation feature on the developer portal on a regular schedule for maximum application security. To ensure consistency in the process, it is suggested that developers define, describe, document, and agree on a standard process around client-secret rotation with the rest of their team. A well-defined process will ensure that rotating an application’s client-secret is never a pain and that there are no missed steps during application validation with the newly generated client-secret.
