Ring Developer Portal — FAQ & Certification Best Practices

Frequently Asked Questions

Below are answers to questions frequently asked by developers. They are grouped in the following categories:

Account Linking, Authentication & Unlinking

Clarifies that only browser-based OAuth flow is supported (no app-to-app login), provides guidance on nonce matching and unclaimed token pool management, and describes triggering conditions and recommended cleanup actions for account unlinking.

Device Capabilities & Control

Confirms capability fields in the Devices API are currently read-only with no active control functionality.

Motion Detection

Confirms events fire only for motion within configured detection zones.

Testing & Certification

Explains how to test production endpoints prior to certification and how to ensure smooth certification checks.

Account Linking, Authentication & Unlinking

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_id through HMAC-SHA256(K_hmac, f"{timestamp}:{account_id}")
• Only the correct account_id will produce a matching nonce when computed
• Constant-time comparison is used to prevent timing attacks (reference time provided along with the nonce as query parameters of the forward URL)

Important implementation notes:

• The nonce must be encoded as URL-safe Base64 without padding (A-Z, a-z, 0-9, -, _, no =). Standard Base64 (which uses +, /, and = padding) will produce a different string. In Java: Base64.getUrlEncoder().withoutPadding(), in Python: base64.urlsafe_b64encode(...).rstrip(b'=').
• The time parameter is in milliseconds (Unix epoch), not seconds. Ensure your HMAC payload uses the millisecond value as-is.
• The HMAC signing key is the same key used for webhook signature verification, but webhooks use hex encoding (.hexdigest() + sha256= prefix) while nonces use URL-safe Base64. Do not mix the two.
• Nonce matching must only execute after the user has signed in to your partner service. Ring's certification process verifies that users explicitly authenticate before nonce validation occurs.

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.

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

---

Testing & Certification

Q5. How can I test my production endpoint on account linking prior to app certification?

You can test your production account linking environment by copying your production endpoint URLs into your staging environment configuration and using the test feature. This allows you to verify that your production environment without needing a separate staging account.

Q6. How do I make sure certification checks go smoothly for my app?

Go through the Best Practices — Before Submission checklist items, as we see certification being rejected due to missing required items from this list.

The Ring certification team uses your production environment account linking to test account linking and functionality of your application. Make sure to test your production endpoint on account linking prior to submitting your app for certification.

In Ring Developer Portal, when submitting for certification, there are fields to add notes for the reviewer. Provide details about how the reviewer should create a new account on your platform, how they should perform account linking step by step, and provide as much detailed information as possible so that certification testing goes smoothly.

---

Device Capabilities & Control

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

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

---

Certification Best Practices

Before Submission

1. Verify Configuration Details
   • App name is accurate and professional
   • Description clearly explains app functionality
   • Tags accurately represent your app's category
   • Features list is correct (e.g., Liveview)
   • OAuth scopes match your requirements (e.g., ava.devices)
   • App logo is high quality (PNG, 512x512px recommended)
2. Test All Configured Endpoints
   • partnerConfigUrl is accessible and returns valid JSON
   • partnerLinkUrl handles account linking requests
   • redirectUrl matches your OAuth implementation exactly
   • webhookUrl accepts POST requests and returns HTTP 200
   • All URLs use HTTPS (required for production)
   • Endpoints are deployed to production environment
3. Validate OAuth Implementation
   • OAuth flow works end-to-end with configured endpoints
   • Authorization requests are handled correctly
   • Token exchange works properly
   • Redirect URL matches configuration exactly (including trailing slash)
4. Test Webhook Endpoint
   • Endpoint accepts POST requests with JSON payload
   • Returns HTTP 200 within 5 seconds
   • Handles Ring's webhook payload format
   • Signature verification implemented (if required)

During Review

1. Monitor Status: Check the portal regularly for certification updates
2. Keep Endpoints Stable: Don't modify or take down configured endpoints during review
3. Monitor Endpoint Logs: Watch for Ring Team testing your endpoints
4. Respond Quickly: Address any questions or feedback from Ring Team promptly
5. Be Available: Ensure your team can respond to configuration issues

After Submission

1. Don't Change Configuration: Avoid modifying endpoint URLs during active review
2. Maintain Endpoint Availability: Keep all configured endpoints operational and responsive
3. Monitor for Test Traffic: Ring Team will test your endpoints - ensure they respond correctly
4. Prepare for Feedback: Be ready to update configuration if issues are found
5. Plan Next Steps: Prepare for the Publish phase once certification passes

---