Ring API Development Guide
Overview
Developing applications for the Ring App Store follows a three-phase lifecycle: Configure, Build, and Test. During the Configure phase, you'll complete partner onboarding, obtain client credentials, and implement OAuth 2.0 account linking to authenticate users. The Build phase involves integrating with the Ring API to access device management, capabilities, status, location, and configuration data, as well as implementing webhooks for real-time event notifications. Finally, in the Test phase, you'll validate your implementation in a staging environment, verify error handling and token management, test webhook delivery, and ensure compliance with rate limits and security best practices before deploying to production.
Configure
The Configure phase is the foundation of your Ring App Store integration. During this phase, you'll complete partner onboarding to register your application and receive client credentials (client ID, client secret and HMAC Key). These credentials enable your app to authenticate Ring users through OAuth 2.0 account linking and access the Ring API.
The configuration process involves registering your application details, including app name, description, category, and support information. You'll also provide essential URLs such as your privacy policy, terms of service, and support contact. These details help Ring users understand your application's purpose and how their data will be handled before they authorize access to their Ring devices.
A critical part of configuration is setting up OAuth 2.0 endpoints and webhook URLs. You'll define an Account Link URL where Ring redirects users for authentication, a Token Exchange URL where Ring obtains access tokens, and a Webhook URL to receive real-time device event notifications. Ring provides separate staging and production environments, allowing you to test your integration thoroughly before deploying to live users.
For detailed step-by-step instructions on completing the configuration phase, see Configure Your Ring Application.
Build
The Build phase is where you integrate with the Ring API to create your application. Ring API follows the JSON:API specification and provides a comprehensive set of endpoints for device management, including device discovery, capabilities, status monitoring, location information, and configuration retrieval. All API requests use the base URL https://api.amazonvision.com and require OAuth 2.0 Bearer token authentication obtained through the account linking flow.
Device discovery is the entry point for accessing Ring devices, returning a list of devices the authenticated user has authorized your application to access. Each device provides relationships to status, capabilities, location, and configurations, which you can fetch individually or include in a single request using the include parameter. Device capabilities describe what features each Ring device supports, such as video streaming, motion detection, and image enhancements like night vision and HDR.
Real-time event notifications are delivered through webhooks, which POST JSON payloads to your configured endpoint. The API supports three webhook types: motion detection events, device addition notifications, and device removal events. Your webhook endpoint must accept HTTPS POST requests, return HTTP 200 within 5 seconds, and implement idempotency using the request_id field to prevent duplicate processing.
The API enforces a rate limit of 100 requests per second, so implementing exponential backoff for rate limit errors and caching device information is essential. Best practices include proper error handling for token expiration and HTTP errors, automatic token refresh using refresh tokens, comprehensive logging of API calls, and respecting user privacy settings such as privacy zones in video processing.
Ring MCP
Ring MCP (Model Context Protocol) is the recommended approach for building Ring App Store integrations. Ring MCP connects your AI coding assistant directly to Ring Appstore documentation, enabling it to instantly access API references, integration guides, and technical specifications without leaving your IDE. Instead of manually searching through documentation, your AI assistant can automatically search indexed docs, retrieve full documents, and generate working code from real Ring API documentation. This dramatically accelerates development by providing context-aware code generation, real-time API guidance, and accurate answers with source references as you build your integration.
To get started with Ring MCP and accelerate your development, see Ring MCP Server.
API
For experienced developers who prefer full control over every aspect of their code, the Ring API provides a comprehensive REST interface for direct integration. This approach gives you complete flexibility to implement custom error handling, optimize performance for your specific use case, and maintain granular control over API calls, authentication flows, and webhook processing. The API follows the JSON:API specification and includes endpoints for device discovery, capabilities, status monitoring, location information, configuration retrieval, and real-time event notifications through webhooks.
For complete API specifications, endpoint details, and implementation guidance, see Ring API Documentation.
GitHub sample projects
Ring publishes two open-source sample projects. Start with Watchtower to see a complete app built to the UX design guide and the certification requirements. Use Hello World to experiment with live video and video processing.
Watchtower
Watchtower is a minimal reference app for watching many Ring cameras live on one screen, such as a lobby monitor or a front-desk display. It's small enough to read end to end, and it shows how passwordless account linking, signed webhooks, and WHEP live streaming fit together. It deploys to AWS (API Gateway, Lambda, and DynamoDB) with one command, which prints the URLs you enter on the Account linking page.
Watchtower follows the UX design guide and scores 98% on the certification preflight checklist. Its README explains what a production app still needs, such as a scheduled token refresh job.
Hello World
The Ring Partner API Hello World sample application is a production-ready Next.js dashboard that demonstrates comprehensive integration with the Ring Partner API. Built with TypeScript and React, it showcases real-time video streaming via WebRTC/WHEP protocol, webhook event processing through Server-Sent Events (SSE), and an extensible video processor plugin system. The application features a live video feed with canvas overlays for bounding boxes and visual effects, a real-time event panel displaying webhook notifications with filtering capabilities, and interactive video processors including a hand-tracking game powered by MediaPipe Hands.
The architecture follows modern best practices with composable React components, custom hooks for WebRTC connection management and SSE auto-reconnect, and a plugin-based video processor registry. The sample includes three built-in processors: a catch-the-box game using hand detection with fire effects, a motion heatmap visualizer that tracks movement across frames, and a brightness analyzer that highlights exposure levels. The application handles OAuth 2.0 token management with automatic refresh, normalizes Ring's JSON:API webhook payloads, and provides both staging and production configuration support.
Developers can use this sample as a foundation for building their own Ring integrations, learning the complete OAuth flow from authorization to token exchange, implementing WebRTC video streaming with proper session management, processing real-time webhook events with idempotency checks, and creating custom video processors using the provided plugin interface. The codebase demonstrates error handling, rate limiting with exponential backoff, and proper cleanup of resources including WebRTC connections and MediaPipe models.
The complete source code and setup instructions are available in the ring-api-helloworld GitHub repository.
Code Snippets
The Ring API enables developers to build powerful integrations across multiple use cases. Smart home integrations can trigger automations based on motion detection, such as turning on lights, sending notifications, and starting video recordings when activity is detected at Ring doorbells. Security monitoring dashboards provide real-time visibility into all Ring devices, displaying online/offline status, recent motion events, device locations, and configuration settings with summary statistics and event tracking. Motion-triggered recording systems automatically capture video clips when motion is detected, with intelligent filtering based on configured motion zones, device status verification, and automated thumbnail generation for notifications.
These use cases demonstrate practical implementations with complete Python code examples, including OAuth token management, device discovery and capability checking, webhook event processing with idempotency, real-time status monitoring, and video recording workflows. Each example follows best practices for error handling, API rate limiting, and respecting user privacy settings such as privacy zones.
For complete code examples and implementation details, see Ring API Use Cases.
Test
The Test phase lets you check your integration before you submit it for certification. The Testing page has two tabs:
- Test with Ring account — Authorize up to 10 Ring accounts as staging users, then test your OAuth flow, API calls, and webhooks with real Ring devices against the staging version of your app. See Testing Process.
- Validate account linking — Have Ring run your one-way account linking flow end to end against the account linking URLs you saved for staging or production. Validating your production settings is one of the steps you must complete before you can submit for certification. See Validate Account Linking.
Before testing, complete the Configure phase, with your app information and account linking URLs saved, and the Build phase, with your OAuth flow, API integration, and webhook endpoint deployed.
Overview
Purpose: Test your app using your Ring accounts to verify end-to-end functionality
Location: Amazon Developer Portal → Ring Section → Test (Phase 3)
Description: "Test your app using your Ring accounts"
Key Features:
- Test with up to 10 staging users
- Validate OAuth authorization flow
- Verify API integration with real Ring devices
- Test webhook delivery and processing
- Ensure endpoints respond correctly
- Validate your saved staging and production account linking URLs from Ring's environment
Prerequisites
Before testing, ensure you have completed:
- Configure Phase
- App information configured
- OAuth endpoints configured (staging environment)
- App logo uploaded
- Build Phase
- OAuth flow implemented
- API integration completed
- Webhook endpoint deployed
- All endpoints accessible via HTTPS
- Ring Account
- Ring account with an active Ring Protection subscription plan
- Two-factor authentication enabled (if applicable)
- Ring devices registered to your account (for full testing)
The Ring Protection plan activates cloud features on the Ring devices you test against. It's a requirement of the Ring account itself and is separate from any fee your app charges — staging users never purchase your app to test it.
Validate Account Linking
Pre-submission account linking validation runs your real one-way account linking flow end to end, from Ring's environment, against the account linking URLs you saved in the Configure phase. Ring follows your Account Link URL, signs in on your page, completes the token exchange with your Token Exchange URL, and confirms that the integration becomes active. Running it before you submit catches broken account linking while you can still fix it, rather than in a certification review cycle.
The validation covers one-way account linking, including passwordless one-way account linking. It doesn't test webhooks, token refresh, or the rest of your app.
The Validate account linking tab has one section for each environment:
| Section | What it tests |
|---|---|
| Validate production settings | Your saved production URLs. Required: a validated production run completes the Production settings validated step on the Certify page. |
| Validate staging settings | Your saved staging URLs. Optional: use it during development; it doesn't affect certification. |
Validate your production settings only after your production endpoints are deployed and reachable. Ring calls them directly.
Step 1: Open the Validate Account Linking Tab
- From your app's overview page, click Test.
- On the Testing page, click the Validate account linking tab.
To read what a run does and doesn't do, click Learn more in either section. Close About validation to return to the tab.
Step 2: Review the Saved URLs
Click the arrow next to a section to expand it. The section lists the Account Link URL, App Homepage URL, and Token Exchange URL that the run will use. These are the values saved on the Account linking page for that environment. Unsaved edits aren't tested. To change a value, go to Configure > Account linking, edit it on the Production settings or Staging settings tab, save, and return to this tab. See Account Linking.
Step 3: Start the Validation
- Click Validate production settings or Validate staging settings.
- Review the Before you start validation dialog. It confirms that Ring uses your saved configuration, that the run may create test accounts or records in your system that you can identify and remove, that no Ring customer data is used, and that a pass doesn't guarantee certification.
- Click Start validation. Click Cancel to close the dialog without starting a run.
Step 4: Follow the Validation
While the run is in progress, the section shows Validation in progress and a progress bar. A run usually takes about 5 minutes.
The progress bar tracks three stages. A completed stage shows a green check mark; a stage where the run stopped shows a red ✕.
| Stage | What it covers |
|---|---|
| Sign-in redirect | Ring starts the linking flow and reaches the sign-in page at your Account Link URL. |
| Account link | Ring signs in or creates an account on your page and links it. |
| Integration active | The token exchange completes and the integration becomes active. |
Step 5: Review the Result
| Result | What it means | What to do |
|---|---|---|
| Validated | Ring completed the account linking flow and confirmed an active integration. The result shows the date, time, and version of the run. | Nothing more for this environment. For production, the Certify page now shows Production settings validated. To run it again, click Re-validate. |
| Validation error | The run couldn't complete. The message says why, for example "Validation couldn't be completed due to an internal error. Please try again." | Click View issue details to find out what happened, then run the validation again. See Step 6. |
If you change your Account Link URL, App Homepage URL, or Token Exchange URL after a validated run, validate that environment again.
If your sign-in page doesn't use passwordless account linking, a validated result also shows Ring recommends passwordless account linking, with a link to Reducing Account Linking Drop-Off. The recommendation doesn't stop the run from validating.
The following diagram shows how your actions and the run's outcomes connect these states.
Step 6: Resolve a Validation Error
Click View issue details to open What happened. It explains where the run stopped and whether the cause is on your side or Ring's. If the cause is on Ring's side and your configuration is correct, you don't need to do anything; Ring investigates it.
To resolve the error:
- Read What happened, then close it.
- If it points to your configuration or endpoints, fix the problem. If you change a URL, save it on the Account linking page and return to this tab.
- Click Validate production settings or Validate staging settings to run the validation again.
Step 7: Continue to Certification
When your production settings are validated, the Certify page shows Production settings validated, with the date and version of the run. A staging result doesn't change the Certify page.
Complete the remaining steps on the Certify page, then submit your app. See Certify Your Ring Application.
Testing Process
The following steps cover the Test with Ring account tab.
subscription_activated or subscription_deactivated webhooks, and the Subscriptions API returns no active subscriptions for them. Production is unchanged — customers who install a paid app still go through subscription activation. To test your subscription handling before you publish, see Testing subscriptions. For the announcement, see the September 11, 2026 release notes.Step 1: Access Testing Page
Navigate to the Test section in the Amazon Developer Portal, Ring section.
Page Title: "Testing"
Description: "Test your app using your Ring accounts"
Step 2: Review Staging User Limit
The testing page displays your current staging user count:
Status Box: "0 staging users out of 10"
Description: "Current number of authorized users can see and connect to the staging version of your app."
Important Notes:
- Maximum 10 staging users allowed
- Staging users can access and test your app integration
- Staging users don't purchase or subscribe to your app, even if your app is paid
- Use the Remove all button to clear all staging users if needed
Step 3: Initiate Login with Ring
Click the Log in with Ring button to begin the authorization flow.
This will redirect you to the Ring login page to authenticate with your Ring account.
Step 4: Ring Account Login
You'll be redirected to the Ring login page:
Login Form:
- Email: Enter your Ring account email address
- Password: Enter your Ring account password
- Show: Toggle to show/hide password
Actions:
- Click Sign In to proceed
- Click Forgot Password? if you need to reset your password
Terms: "By clicking Log In, I agree to the Ring Terms of Service. See Privacy for additional information."
Where This Information Comes From:
- Email: Your existing Ring account email (the account you use for the Ring app)
- Password: Your Ring account password
Important: Use a Ring account that has Ring devices registered for comprehensive testing.
Step 5: Two-Factor Authentication (If Enabled)
If your Ring account has two-factor authentication enabled, you'll see:
Two Factor Authentication Code:
- Enter the 6-digit code sent to your registered phone number
- Format:
+1xxxxxxxxx [ ](shows masked phone number)
Error Handling:
- If code is incorrect: "Please enter your two factor authentication code sent to +1xxxxxxxxx [ ]"
- Request new code if needed
Actions:
- Enter the authentication code
- Click Sign in to proceed
Where This Information Comes From:
- Authentication Code: Sent via SMS to your phone number registered with Ring
- Check your phone for the 6-digit code
Step 6: Authorize Application
After successful login, you'll see the authorization consent screen:
Page Title: "Authorize Application"
Application Name: "Ring Developer Portal (Beta)" (or your app name in production)
Permission Request: "would like permission to access your account"
Review permissions:
- Access all Ring devices registered to your account
- Access third-party devices you have also linked to your Ring account
- Access your Ring account and settings
Revocation Notice: "If you want to revoke this permission, you can disable it at anytime."
Actions:
- Click Authorize to grant permissions and proceed
- Click Deny to cancel authorization
What Happens When You Authorize:
- Your Ring account is linked to the staging version of your app
- Your app receives an authorization code
- Your app exchanges the code for access and refresh tokens
- Your app can now access Ring API on behalf of your account
Step 7: Verify Staging User Added
After successful authorization, you'll be redirected back to the Testing page:
Updated Status: "1 staging users out of 10"
Description: "Current number of authorized users can see and connect to the staging version of your app."
What This Means:
- Your Ring account is now authorized as a staging user
- You can test API calls with your account's access token
- Your app can discover devices registered to your account
- Webhooks will be sent for events on your devices
Actions Available:
- Log in with Ring: Add more staging users (up to 10 total)
- Remove all: Remove all staging users and start over
Related topics
- Ring Partner API Documentation — Complete API reference and integration guide
- Ring Appstore MCP Server — AI-assisted development with Ring Appstore documentation
- Configure Your Ring Application — App registration, credentials, and endpoint setup
- Certify Your Ring Application — Certification process and submission guide

