Refresh Tokens

Ring now requires the use of Two-Factor Auth (2fa) for all accounts. If you have not turned on text-based 2fa, you will receive a verification code via email instead. For automation purposes (like homebridge-ring and ring-client-api) we need a special refreshToken that can be used long-term with 2fa turned on. A refreshToken allows us to bypass email/password/2fa altogether. To get a refreshToken, run one of the following commands on any computer with node installed:

The Easy Route

• Install homebridge-config-ui-x, which will give you a UI through which you can enter your Ring credentials to get logged in. No command line required ✨

Manually run the cli tool

• npx -p ring-client-api ring-auth-cli

After entering your information, you will see a refreshToken in the output. Copy the token and open up your config file for homebridge or whatever platform is using ring-client-api. Remove your email and password values as these will no longer be used, and add "refreshToken": "TOKEN FROM COMMAND ABOVE". Restart your home automation app (homebridge, etc.) and Ring should authenticate successfully.

Note: Your refreshToken is just as valuable as an email/password so treat it with the same care you would a password. It can also be used for accounts that do not have 2fa enabled if you don't want your email/password in plain text in a config file.

Refresh Token Updates

The steps above generate an initial refresh token that can used to authenticate during the initial connection to the Ring API, however, immediately after this connection is established, and at various intervals (typically every hour), an updated refresh token will be generated. Consumers of the ring-client-api library MUST subscribe to api.onRefreshTokenUpdated to get the new refresh token each time a new one is created. This new refresh token should be stored wherever your library stores its configuration. See here for an example.

!!!IMPORTANT NOTE!!!
It may seem possible to simply re-use the initially generated token multiple times, and indeed it will generally work for authentication even if newer tokens are not saved, however, this will have a significant negative consequence, specifically, push notifications will not work for any future connections. Push notifications are used to receive ding and motion events from Ring doorbells, cameras, and intercoms. If everything else is working, but you are not able to receive ding and motion events from these devices, then the only fix is to delete the client from Ring Control Center and repeat the authentication process, being sure to capture all token updates.

The reason for this behavior is that the initial authentication process only generates the refresh token itself, however, during the initial API connection, ring-client-api has to additionally register itself with the Firebase Cloud Messaging service and send this required information to Ring so that push notifications can be properly directed to ring-client-api. Once the FCM registration is done and the information sent to Ring, it is not possible to change it for that registered device going forward, thus ring-client-api must reuse the same FCM registration each time it is reinitialized. To accommodate this requirement the FCM registration data is encoded with the updated token.

If the updated token with this additional FCM registration data is not saved, but instead the generated refresh token is used a second time, ring-client-api will repeat the FCM registration process from scratch, but Ring will refuse to use this updated FCM information because it only accepts this information during initial device registration. Instead Ring will continue to send push notifications using the original FCM registration and thus these notifications never arrive to ring-client-api. The only fix from that point is to delete the client from Ring Control Center and repeat the process.