-
-
Notifications
You must be signed in to change notification settings - Fork 161
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:
- 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 ✨
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.
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.