Ring App Challenge Developer Onboarding Kit

On this page

• Getting Started with Ring APIs
• Core API Reference Guide
• Backend Architecture Guide
• Testing & Sandbox Guide
• Use Case Ideas & Inspiration
• Content Policy
• App Submission & Certification
• Certification Tips & Error Handling
• Sample Code & Templates

Getting Started with Ring APIs

Welcome to the Ring App Challenge. This guide will help you go from zero to building your first Ring Appstore app. The Ring Appstore enables developers to create innovative applications that enhance the security, safety, and functionality of Ring devices.

What You Can Build

Ring APIs give you access to a rich set of capabilities:

• Device Discovery: List and query Ring cameras, doorbells, sensors, and chimes shared by the user.
• Event History: Access motion, doorbell press, live view, and other device events with timestamps and metadata.
• Live Video: Stream live video from Ring cameras using WebRTC/WHEP or RTSP protocols.
• Media Clips: Download recorded video clips (MP4), and image snapshots (JPEG).
• Webhooks: Receive real-time push notifications for device events, subscription lifecycle events, and account changes.
• Sensor Data: Access contact sensors, flood/freeze sensors, temperature/humidity, and air quality monitors. Sensor support is Early Access: you can build against it, but publishing depends on dynamic scopes reaching general availability.

Developer Account Setup

To get started, you need a Ring Developer Portal account. Then create your app in the portal. You don't need to have built anything yet: creating the app gives you the credentials you use to start building.

Creating the app asks only for an internal name, the app type, and the API scopes your app needs. The portal then shows your Client ID, Client Secret, and HMAC Signature Key. They are shown only once, so store them securely. See Configure Your Ring Application for each step.

Before your app can use a customer's devices, the customer must connect their Ring account to it. This is called account linking. Customers start it from the Ring Appstore. Ring then sends your backend the tokens it needs to call the Ring API for that customer, and sends the customer to your app to sign in or create an account. For this to work, Ring needs a few URLs from you:

• Account Link URL: the page where the customer signs in to your app.
• Token Exchange URL: the backend endpoint where Ring sends the code your app exchanges for tokens.
• Webhook URL: the endpoint where Ring sends events, such as motion alerts and device changes.

You enter these URLs in a separate Configure step that stays Pending until you complete it, so you can add them once your backend is running. This guide explains them in OAuth 2.0 Account Linking, Webhook Notifications, and the Backend Architecture Guide.

API Architecture Overview

The Ring Partner API follows a RESTful architecture and uses the JSON:API specification for most endpoints:

• Base URL: https://api.amazonvision.com
• Authentication: OAuth 2.0 access and refresh tokens. Access tokens last about 4 hours and refresh tokens about 30 days, rotating on every exchange. Read expires_in from the token response rather than hard-coding a lifetime.
• Format: JSON:API responses for most endpoints, with included relationships for efficient data loading.
• Rate Limiting: All endpoints are rate-limited. Implement exponential backoff on 429 responses.
• Webhooks: Server-to-server push notifications authenticated with HMAC-SHA256 signatures.

AI-Assisted Development with Ring MCP

Ring provides a Model Context Protocol (MCP) server that integrates with AI coding assistants such as Claude, Cursor, and Kiro. The Ring MCP server gives your AI assistant direct knowledge of Ring API endpoints, authentication flows, and webhook schemas, so it can generate accurate integration code and help you troubleshoot issues faster.

Your First API Call

Once a user has linked their Ring account to your app and you have captured their access token, you can make API calls on their behalf. Here is a quick curl example to list devices:

curl -X GET "https://api.amazonvision.com/v1/devices" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "User-Agent: <app_name>/<version>" \
  -H "Hardware_Id: <user_device_uuid>"

Python example:

import os
import requests

# ACCESS_TOKEN and REFRESH_TOKEN come from account linking (section 2.1).
# Read them from the environment so nothing is hard-coded. Access tokens
# last about 4 hours; when one expires, exchange REFRESH_TOKEN at
# https://oauth.ring.com/oauth/token for a new pair. Keep both
# server-side and never ship them to the browser.
access_token = os.environ["ACCESS_TOKEN"]
refresh_token = os.environ["REFRESH_TOKEN"]  # used when access_token expires
hardware_id = os.environ["HARDWARE_ID"]
BASE_URL = "https://api.amazonvision.com"
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
    "User-Agent": "challenge-app/1.0",
    "Hardware_Id": hardware_id,
}
response = requests.get(f"{BASE_URL}/v1/devices", headers=headers)
devices = response.json()
for device in devices["data"]:
    print(f"Device: {device['attributes']['name']}")

Explore the Developers Playground

Before writing any code, spend time in the Developers Playground to build hands-on familiarity with Ring APIs. The Playground provides a live, interactive environment where you can send real API requests, inspect responses, and understand the data structures you will be working with.

Access the Playground at:

https://developer.amazon.com/ring/console/playground

What to try in the Playground:

• List Devices: Call the /v1/devices endpoint to see the structure of device objects, including attributes like name, type, firmware, and capabilities.
• Fetch Event History: Query /v1/history/devices/{id}/events to see how motion, ding and on_demand events are formatted, including their start and end timestamps.
• Test Media Endpoints: Request a video clip or snapshot to understand each endpoint's download flow.
• Simulate Webhooks: Use the Live View simulation to trigger Package, Vehicle, and Motion events and observe the WebRTC/WHEP session flow.
• Generate curl Commands: Copy ready-to-use curl commands for any API call directly from the Playground to use in your own testing.

Learn from Top Existing Apps

One of the best ways to understand what makes a great Ring Appstore app is to study the apps that Ring customers already use and love. Visit the Ring Appstore to see current apps:

https://ring.com/appstore/category/all-apps

Try out a few apps and pay attention to:

• Onboarding Flow: How do they guide users through account linking? Is the setup process clear and quick?
• Core Value Proposition: What specific problem does the app solve? How quickly does the user see value after connecting?
• UI/UX Design: How do they organize device data, events, and media? Is the interface intuitive and responsive?
• Feature Scope: Are they focused on doing one thing well, or do they try to cover many use cases? Note which approach feels more polished.
• Error Handling: What happens when a device is offline or data is unavailable? Do they degrade gracefully?

Core API Reference Guide

This section covers the core Ring API endpoints and authentication flow you will use in your app.

OAuth 2.0 Account Linking

Ring uses a one-way account linking flow where the Ring customer initiates the connection from the Ring Appstore. When a user installs your app:

• The user finds your app on the Ring Appstore, selects which devices to share, and confirms.
• Ring POSTs an authorization code to your Token Exchange URL, server-to-server. Your backend exchanges it at https://oauth.ring.com/oauth/token for an access token and a refresh token. That token is “unclaimed” — you do not yet know which of your users it belongs to.
• Call GET /v1/users/me with the access token to read the Ring Account ID, and store it with the token.
• Separately, Ring redirects the user’s browser to your Account Link URL with a nonce and a time parameter. That page must establish the partner-side account identity through sign-in, account creation, or a supported passwordless experience — nonce matching runs only after that identity is established.
• Recompute HMAC-SHA256 over “<time>:<account_id>” for each unclaimed token, URL-safe Base64 without padding, and compare it to the nonce with a constant-time comparison. The match identifies the token.
• Claim the token with POST /v1/accounts/me/app-integrations carrying the account_identifier and the nonce, then finalise with PATCH and status: completed. Both calls are required — without the PATCH the integration stays awaiting and never becomes operational.

Device Endpoints

Once authenticated, you can discover and interact with the user's Ring devices:

Event History

Access historical events for a device. The event types are motion (with .human, .vehicle, .animal and .other_motion subtypes), ding for a doorbell press, and on_demand for a live view session:

GET /v1/history/devices/{device_id}/events
    ?event_types=ding,motion.human,motion.vehicle
    &page[key]=<cursor from the previous response's links.next>

Each event carries an event type, start and end timestamps in epoch milliseconds, an is_third_party_reviewed flag, and a relationship to the source device. There are no date-range parameters — page back through results with page[key].

Media Endpoints

Ring supports several media access methods:

Webhook Notifications

Ring sends real-time webhook notifications to your server. Your endpoint must respond with HTTP 200 within 5 seconds. All webhooks are signed with HMAC-SHA256.

Backend Architecture Guide

Your Ring Appstore app needs a backend service to handle account linking, store user tokens, proxy API calls, and receive webhook notifications. This section provides a practical, scalable architecture using AWS services that you can deploy quickly for the challenge.

Recommended Architecture

The following serverless architecture is well suited for a Ring Appstore app. It scales automatically and has no servers to manage:

Architecture Overview

Figure 1 — Serverless reference architecture for a Ring Appstore app.

Backend Components

API Gateway + Lambda (Backend API)

• Token Refresh: Automatically refreshes expired access tokens using the stored refresh token before making Ring API calls.

DynamoDB (Token & Data Store)

DynamoDB stores OAuth tokens and app data with the following recommended table structure:

CloudFront + S3 (Frontend Hosting)

Host your web application frontend as a static site on S3, distributed globally via CloudFront:

• S3 Bucket: Stores your HTML, CSS, JavaScript, and static assets. Configure for static website hosting.
• CloudFront Distribution: Provides HTTPS, caching, and global edge delivery. Point your custom domain here.
• Dynamic Content: Your frontend JavaScript makes API calls to your API Gateway endpoint to fetch Ring data dynamically. This keeps your frontend lightweight and your tokens secure on the backend.

Account Linking Implementation

See One-Way Account Linking for the current token-exchange and account-association flow.

Computer Vision Pipeline Architecture

If your app analyzes camera video or images (package detection, pet monitoring, wildlife spotting, security classification), Ring provides a detailed Computer Vision Guidelines document that covers cost-efficient pipeline architecture, frame selection, tiered inference funnels, Ring-specific media constraints (watermarks, encrypted video), and AWS building blocks. Read the full guide at: developer.amazon.com/docs/ring/computer-vision-guidelines.html

Testing & Sandbox Guide

Ring provides several tools to help you test your integration before submitting for certification.

Setting Up Your Test Environment

Before you can test your app with real devices, you need to set up a staging environment and add test users in the Developer Portal.

See Test Your Ring Appstore Integration for current staging prerequisites, user authorization, and the testing process.

Testing Checklist

Before submitting for certification, verify:

• ☐ OAuth account linking completes successfully with valid nonce handling.
• ☐ Webhook endpoint returns HTTP 200 within 5 seconds for all event types.
• ☐ HMAC-SHA256 signature verification is implemented and rejects invalid signatures.
• ☐ Token refresh logic works when access tokens expire.
• ☐ App handles device offline states and missing data gracefully.
• ☐ Rate limiting is handled with exponential backoff.
• ☐ Account unlinking cleans up stored tokens and user data.
• ☐ All API error responses (401, 403, 404, 429, 503) are handled correctly.

Use Case Ideas & Inspiration

The Ring Appstore already features apps across several categories. Here are ideas to inspire your challenge submission, organized by category. Visit ring.com/appstore to see current listings.

Business Intelligence & Operations

• Package Delivery Analytics Dashboard: Track delivery patterns across multiple properties. Aggregate doorbell press and motion events to visualize delivery times, peak hours, and missed deliveries. Useful for e-commerce businesses and property managers.
• Foot Traffic Counter: Use motion events to estimate visitor counts at storefronts or office entrances. Display hourly, daily, and weekly trends with comparison charts.
• Activity Reporting for Property Managers: Generate weekly or monthly reports summarizing all events across a portfolio of properties with exportable PDFs.

Smart Property Monitoring

• Smart Rental Property Dashboard: Help landlords monitor multiple rental units from a single view. Show device health, recent events, and maintenance alerts across properties.
• Vacation Rental Turnover Monitor: Detect guest check-in and check-out patterns using motion events. Trigger automated workflows (e.g., notify cleaning crew after guest departure).
• Maintenance Alert System: Use sensor data (flood/freeze, temperature) to alert property owners of maintenance issues like water leaks or HVAC failures before they become costly.

Home Safety & Wellness

• Elderly Care Check-In: Monitor motion patterns in a family member's home to detect unusual inactivity. Send alerts if no motion is detected during expected active hours, providing peace of mind for caregivers.
• Pet Monitoring & Activity Alerts: Use indoor camera motion events to track pet activity while owners are away. Alert when unusual activity or prolonged inactivity is detected.
• Neighborhood Safety Dashboard: Aggregate anonymized motion and event data from a user's own devices to create a safety overview of their property perimeter, highlighting activity patterns and quiet periods.

Home Automation & Smart Integrations

• IFTTT-Style Event Triggers: Create custom automation rules: "When doorbell pressed, turn on porch lights" or "When motion detected after midnight, send text alert." Use webhooks to trigger actions in external services.
• Motion Event Heatmaps: Visualize motion event data on a timeline or spatial heatmap to show which areas of a property see the most activity and when.
• Daily Security Summary: Generate an automated morning digest summarizing overnight activity: motion events, doorbell presses, sensor triggers, and device health status, delivered via email or push notification.

Environmental & Sensor Intelligence

• Indoor Climate Monitor: Use temperature/humidity sensors and air quality monitors to track indoor conditions over time. Visualize trends and alert when conditions go outside healthy ranges.
• Flood Risk Early Warning: Use flood/freeze sensor data combined with weather API data to provide proactive alerts about water intrusion risks.

Building with Computer Vision

If your app idea involves analyzing camera video or images (package detection, pet identification, wildlife spotting, vehicle classification), read our Computer Vision Guidelines before you start building. It covers a tiered funnel architecture that keeps your inference costs proportional to relevant events, not raw motion volume. Read Computer Vision Guidelines for Ring Appstore Apps for the full guide.

Content Policy

All apps published on the Ring Appstore must comply with the Ring Appstore Permitted Content Policy. Ring customers expect applications that are safe, secure, and respect their privacy. Understanding these guidelines early will save you from certification rejection.

Core Principles

Review the Ring Appstore Permitted Content Policy for current principles and review requirements.

Prohibited Content & Features

Review Prohibited Surveillance and Enforcement Applications and the remaining Content Policy before selecting a feature.

Required Practices

Review the Ring Appstore Permitted Content Policy and Ring Appstore Program Requirements before building and before submission.

App Submission & Certification

Once your app is built and tested, submit it for certification. The Ring certification team reviews your app to ensure it meets Ring standards. Here is what you need to prepare.

Pre-Submission Checklist

• Complete app metadata: name, description, screenshots, privacy policy URL.
• Ensure all backend services are live and accessible.
• Test on real Ring devices, not just simulated data.
• Verify OAuth flow, webhook handling, and error states work end-to-end.
• Review the Content Policy and ensure compliance.
• Document any non-obvious features in App Review notes.
• Pass automated security scanning.

See Certify Your Ring Application for the current questionnaire, reviewer-note fields, submission acknowledgment, review status, and outcomes.

What Reviewers Check

The certification review covers:

• App functionality matches the description and screenshots.
• OAuth account linking works correctly with proper nonce validation.
• Webhook endpoints respond promptly and handle all event types.
• Security best practices: HMAC verification, token storage, HTTPS everywhere.
• Content policy compliance: no prohibited features, accurate metadata.
• User experience: clear onboarding, error messages, and graceful degradation.
• Privacy: data handling matches your stated privacy policy.

UX Design Guidelines Summary

Ring provides a comprehensive UX design guide. Key principles:

• Clear Onboarding: Guide users through the account linking process with clear instructions and visual feedback.
• Device-Centric UI: Organize your interface around devices, making it easy to switch between cameras, sensors, and doorbells.
• Graceful Error Handling: Show user-friendly messages when devices are offline, tokens expire, or API calls fail.
• Subscription Transparency: Clearly communicate trial periods, pricing, and what happens when a subscription ends.
• Accessible Design: Follow accessibility best practices for color contrast, text sizing, and screen reader compatibility.

Certification Tips & Error Handling

This section points to current certification guidance and provides guidance on proper error handling.

Top Certification Failure Reasons

See Certify Your Ring Application and the Developer FAQ for current certification requirements and common guidance.

HTTP Error Handling Guide

Your app must handle all Ring API error responses gracefully. Here is how to handle each status code:

Webhook HMAC Verification Example

import hashlib
import hmac


def verify_webhook(request_body, signature_header, shared_secret):
    """Verify Ring webhook HMAC-SHA256 signature."""
    expected = hmac.new(
        shared_secret.encode("utf-8"),
        request_body,
        hashlib.sha256,
    ).hexdigest()
    received = signature_header.removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        raise ValueError("Invalid webhook signature")
    return True

Sample Code & Templates

Use these resources to accelerate your development and spend more time on your unique app logic.

Quick-Start Resources

Ring MCP for AI-Assisted Development

See Ring Appstore MCP Server for current capabilities, setup, prompts, and troubleshooting.

Recommended Development Tools

Key Documentation Links

Getting Help

If you run into issues or have questions during development, here are your support channels:

• Ring Developer Documentation: Start with developer.amazon.com/docs/ring/get-started.html for API guides and best practices.
• Ring Developer Community Forum: Join the developer community at community.amazondeveloper.com/c/ring/53 to ask questions, share ideas, and learn from other Ring Appstore developers. This is a great place to get peer advice and see how others have solved similar challenges.
• Developer Support: Open a support case at developer.amazon.com/support/cases/new for technical issues with your app, API questions, or certification inquiries.

Good luck with the Ring App Challenge!

Build something innovative. Solve a real problem. Have fun.

Questions? Reach out to your university challenge coordinator or visit developer.amazon.com/docs/ring/get-started.html