as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
Ring
AWS
文档
Support
Contact Us
My Cases
Ring
感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

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:

  1. Configure Phase
    • App information configured
    • OAuth endpoints configured (staging environment)
    • App logo uploaded
  2. Build Phase
    • OAuth flow implemented
    • API integration completed
    • Webhook endpoint deployed
    • All endpoints accessible via HTTPS
  3. 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

  1. From your app's overview page, click Test.
  2. 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.

Validate account linking tab on the Testing page, showing the collapsed Validate production settings section marked Required for certification and the Validate staging settings section marked Optional for certification

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.

Both sections expanded, each listing its saved Account Link URL, App Homepage URL, and Token Exchange URL, with a Validate production settings button and a Validate staging settings button below the lists

Step 3: Start the Validation

  1. Click Validate production settings or Validate staging settings.
  2. 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.
  3. Click Start validation. Click Cancel to close the dialog without starting a run.
Before you start validation dialog with the sections What Ring will do, Test records, No customer data, and Pass not equal to certify, and the Cancel and Start validation buttons

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.
Validate production settings section showing Validation in progress, the message that the run usually takes about 5 minutes, and a progress bar with Sign-in redirect complete and Account link in progress

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.

Validated production result showing the date, time, and version v2, the message that Ring completed the account-linking flow and confirmed an active integration, a Re-validate button, and the passwordless recommendation
Production and staging sections each showing Validation error with the message that validation couldn't be completed due to an internal error, a View issue details button, and a button to validate again

The following diagram shows how your actions and the run's outcomes connect these states.

On the Validate account linking tab the saved URLs are shown with a Validate settings button. Selecting it opens Before you start validation, where Cancel returns and Start validation begins the run. While Validation in progress, the stages Sign-in redirect, Account link, and Integration active are shown. A completed run shows Validated with the date and version and a Re-validate button. A run that cannot complete shows Validation error with a rerun button and View issue details, which opens What happened. A validated production run updates the Production settings validated item on the Certify page. Open Validate account linking Validate [environment] settings Cancel Start validation Flow completes Run can't complete Re-validate Validate [environment] settings (rerun) View issue details Production run only Saved URLs shown Validate [environment] settings Before you start validation Cancel / Start validation Validation in progress Sign-in redirect > Account link > Integration active Validated [date] · v[n] Re-validate Validation error Validate [environment] settings / View issue details What happened Where the run stopped and what to do Production settings validated Certify checklist item Changing a saved Account Link, App Homepage, or Token Exchange URL requires a new validation. Legend Developer action Run outcome Dialog or note Staging and production runs show the same states. Only a validated production run updates the Certify checklist.

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.

What happened dialog explaining that the account-linking check failed before reaching the partner sign-in page because of a transient error on the Ring side, and that no further action is needed if the configuration is correct

To resolve the error:

  1. Read What happened, then close it.
  2. 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.
  3. 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.

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:

  1. Your Ring account is linked to the staging version of your app
  2. Your app receives an authorization code
  3. Your app exchanges the code for access and refresh tokens
  4. 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