Ring Developer Portal — Developer FAQ
Below are answers to questions frequently asked by developers. They are grouped in the following categories:
Account Linking & Authentication
Clarifies that only browser-based OAuth flow is supported (no app-to-app login), and provides guidance on nonce matching and unclaimed token pool management.
Describes triggering conditions (device removal, deletion, revoked access) and recommended cleanup actions upon receiving device_removed webhook events.
Confirms capability fields in the Devices API are currently read-only with no active control functionality.
Confirms events fire only for motion within configured detection zones.
Account Linking & Authentication
Q1. Does the implementation support only browser-based authentication, or is app-to-app login also an option?
Our Ring one-way account linking implementation supports browser-based authentication only. The web-based flow works as follows:
- Ring user discovers your app in Ring App Store and installs it
- Ring user selects the devices to which the app will have access and confirms scopes
- Ring sends OAuth authorization code to the token exchange URL you specified during App Configuration
- Upon recieving the OAuth authorization code in the toke exchange URL, you exchange it by access and refresh tokens, and save both along with the Account ID (retrieved from the request to /v1/users/me)
- Ring redirects users to your Account Link URL with query parameters (time and nonce)
- Users must sign in to your partner service through your web interface — this step is mandatory
- After the user successfully signs in, the nonce provided in the redirect is matched against an unclaimed token. Once a match is found the one-way account link is started.
App-to-app login is not supported at this time.
Q2. When querying for unclaimed tokens during nonce matching, should the query include additional parameters beyond status?
No. The query should use only status = 'UNCLAIMED' without additional parameters. This is the documented approach. Your current implementation using the StatusIndex with KeyConditionExpression=Key('status').eq('UNCLAIMED') is correct.
The nonce-to-token matching is designed to iterate through all unclaimed tokens because:
- The nonce cryptographically binds to a specific
account_idthroughHMAC-SHA256(K_hmac, f"{timestamp}:{account_id}") - Only the correct
account_idwill produce a matching nonce when computed - Constant-time comparison is used to prevent timing attacks (reference
timeprovided along with the nonce as query parameters of the forward URL)
Q3. What is the expected load, and how many unclaimed tokens should be maintained in the pool at any given time?
Every nonce matching request will iterate through all unclaimed tokens across all clients. However, the pool should naturally remain small in practice. The system uses a 600-second (10-minute) timestamp validation window, within which tokens should transition from unclaimed to claimed status promptly.
The documentation does not specify an exact number of unclaimed tokens to maintain — pool size depends on your integration's traffic patterns. We recommend the following:
- Implement automatic cleanup of stale unclaimed tokens older than 10 to 15 minutes
- Monitor your unclaimed token pool size actively
- Set up CloudWatch alarms for DynamoDB capacity and throttling
The design assumes tokens are claimed within minutes of creation, keeping the unclaimed pool small at any given time.
Account Unlinking
Q2. I did not find documentation on user unlinking. Under what circumstances should we consider an account as unlinked, and what actions should we take?
Unlinking occurs under the following circumstances:
- A user explicitly removes the device from a partner integration
- A user deletes the device from their Ring account
- A user revokes partner access permissions
When you receive a device_removed webhook event, you should take the following actions:
- Immediately clean up resources and terminate any active sessions
- Implement graceful termination of active video streams and scheduled operations
- Archive important data before cleanup for audit purposes
Note: The Ring API will return 404 errors for all requests to devices that have been removed.
Device Capabilities & Control
Q3. The Devices API returns capabilities such as zoom track and IR control. Does this indicate that future integration phases will support device control functionality beyond live streaming?
At this time, device capability values returned in the Devices API are read-only. They do not indicate active control functionality. If you have specific ideas or requirements around device control, we encourage you to share them — partner input directly informs our roadmap.
Motion Detection
Q4. Are motion events sent whenever motion is detected within a specified detection zone, or are they sent regardless of whether the motion falls within the zone?
Motion events are sent only when motion is detected within the specified zone. Detection zones are defined with normalized coordinates (0.0 to 1.0 range), with a UUID id and vertices arrays. The detection zone configuration affects how the device processes motion at the hardware level, so events will not fire for motion outside the configured zone.
