Ring Partner API Documentation

Overview

Ring provides device capabilities to partners while ensuring a high bar for security, transparency, and control for users. This API enables partners to:

• Authenticate users through OAuth 2.0 with one-way account linking
• Discover and access Ring devices with proper permissions
• Receive real-time notifications for device events
• Stream live video content using WebRTC/WHEP protocol
• Download historical video clips in MP4 format

Key Features

API Standards

The Ring Partner API follows these standards:

• JSON:API Specification for most endpoints
• OAuth 2.0 for authentication
• WebRTC/WHEP for live video streaming
• Standard HTTP for media downloads

Getting Started Steps

1. Review the Architecture - Understand the end-to-end deployment flow before building.

2. Authentication Setup - Implement OAuth 2.0 token exchange and one-way account linking with HMAC nonce verification.

3. Retrieve User Profile - Call the Users API to get the Ring Account ID for nonce matching and event correlation.

4. Confirm Account Link - Complete the two-step POST + PATCH flow to finalize the integration.

5. Device Discovery - Discover Ring devices, capabilities, and status through JSON:API.

6. Webhook Notifications - Set up webhook endpoints to receive real-time device events with HMAC signature verification.

7. Live Video Streaming - Stream live video from Ring devices using WebRTC/WHEP.

8. Media Clips - Download historical video clips in MP4 format.

9. Image Snapshots - Download image snapshots in JPEG or PNG format.

Quick Links

• 🏗️ High Level Architecture
• 🔐 Authentication Guide
• 📱 Device Discovery
• 👤 Users API
• 🔗 App Integrations
• 🔔 Webhook Notifications
• 📹 Live Video Streaming
• 🎬 Media Clips
• 📋 Error Handling

API Reference

Base URL

All API requests should be made to:

https://api.amazonvision.com

Authentication

All API requests require authentication using OAuth 2.0 Bearer tokens:

Authorization: Bearer <access_token>

Rate Limiting

• Default rate: 100 requests per second (TPS) per partner
• Scope: Rate limits apply per partner client_id across all endpoints

Rate Limit Headers

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests. Use exponential backoff starting at 1 second and respect the Retry-After header.

Content Types

• JSON APIs: application/json
• Media streaming: application/sdp
• Media downloads: Binary content with appropriate MIME types

Authentication Endpoints

Exchange Authorization Code

Request:

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
client_id=<partner_client_id>
code=<authorization_code>
client_secret=<partner_client_secret>

Response:

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Refresh Access Token

Request

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=<refresh_token>
client_id=<partner_client_id>
client_secret=<partner_client_secret>

Response:

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Endpoint Reference

All device and media endpoints require Authorization: Bearer <access_token>. Responses follow JSON:API format.

Device Endpoints

Media Endpoints

Account & Integration Endpoints

Webhook Events

Partners receive webhook notifications at their configured endpoint. All webhooks include an HMAC-SHA256 signature in the X-Signature header. See Notifications for full details.

Event Types

Error Responses

All errors follow JSON:API format. See Error Handling for comprehensive details.

Common Error Codes

• 400: Bad Request — Invalid parameters
• 401: Unauthorized — Invalid or expired token
• 403: Forbidden — Insufficient permissions
• 404: Not Found — Resource not found
• 429: Too Many Requests — Rate limit exceeded
• 500: Internal Server Error
• 503: Service Unavailable — Device offline

Testing Your Integration

Recommended Tools

There is no official Ring Partner SDK. Use standard HTTP libraries and tools:

Testing with curl

curl -X GET 'https://api.amazonvision.com/v1/devices?include=status,capabilities' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -v

SDKs and Libraries

JavaScript/TypeScript

const response = await fetch('https://api.amazonvision.com/v1/devices', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});
const devices = await response.json();

Python

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}
response = requests.get('https://api.amazonvision.com/v1/devices', headers=headers)
devices = response.json()

Application Deployment

This document defines the end-to-end deployment architecture for a partner application integrating with the Ring AppStore. It covers the complete journey from initial app creation and credential setup through endpoint configuration, authentication orchestration, device access, and webhook event delivery.

1. Prerequisites and Setup

Before deploying your application, you must create your app in the Ring Developer Portal, obtain credentials, configure your endpoints, and prepare your backend services.

1.1 Create Your Application

Register your application in the Ring Developer Portal. See Configure Your Ring Application for the complete step-by-step registration process.

1. Click Create new app and provide your app name
2. Accept Ring's security and privacy standards
3. Complete the app information form (description, category, website, support email, privacy policy, terms of service, app icon)

1.2 Obtain Credentials

When you create your application, Ring issues three credentials. These are shown only once — store them securely before continuing.

These credentials are shared across staging and production environments. Never commit them to version control — use environment variables or a secrets manager.

1.3 Configure Endpoints

Register the following HTTPS endpoints in the Ring Developer Portal:

Configure staging endpoints first, validate your integration, then configure production endpoints. See Configure Your Ring Application for detailed requirements.

1.4 Set Up Your Backend

Before a Ring user installs your app, your backend must be ready to handle:

• Token exchange — Receive authorization codes at your Token Exchange URL and exchange them within 60 seconds (Section 5)
• Token storage — Securely store access tokens (~4 hour lifetime) and refresh tokens (~30 day lifetime) with associated Account IDs
• Nonce matching — Implement HMAC-SHA256 nonce verification for account linking (Section 6.3)
• Webhook handler — Accept HTTPS POST requests, verify HMAC signatures, and return HTTP 200 within 5 seconds (Section 9)
• API client — Call Amazon Vision APIs with Bearer token authentication for device discovery, live video, and media downloads (Section 8)

2. App Deployment Journey

2.1 Lifecycle Overview

2.2 Phase Summary

3. Service Architecture Overview

The Ring AppStore follows a one-way account linking model where Ring manages the OAuth credential lifecycle and partners verify messages through HMAC digital signatures. Partners do not need to operate as OAuth servers.

3.1 Security

Ring takes security seriously. Our account linking mechanism ensures security through cryptographic verification, time-bound validation, and mandatory user authentication. All communications use HTTPS, and access tokens are scoped to specific devices and operations authorized by the user.

3.2 High-Level Service Architecture

3.3 Component Responsibilities

4. Endpoint Configuration

Partners must configure endpoint categories to complete an integration. These are registered via the Ring Developer Portal during app creation.

4.1 Partner-Hosted Endpoints

4.2 Ring-Hosted Endpoints — Amazon Vision API

See API Reference for full details.

5. Token Exchange Flow

After a Ring user installs a partner app, Ring Backend generates an OAuth authorization code and sends it to the Partner App Backend.

5.1 What Triggers This Flow

1. The user discovers your app in the Ring AppStore
2. The user reviews the data access scopes your app requests
3. The user selects which Ring devices to share with your app
4. The user clicks Confirm to approve the integration

Ring Backend then generates an OAuth authorization code and sends it directly to your Token Exchange URL (backend-to-backend).

5.2 Token Exchange Sequence

5.3 Token Lifecycle

5.4 Token Refresh

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>

See Refresh Tokens for implementation guidance.

6. Account Linking Flow (One-Way Account Linking)

The one-way account linking model eliminates the need for partners to act as OAuth servers. Ring releases credentials upfront and redirects the user to the partner for account association.

See also: Account Linking and App Integrations API

6.1 Client State Machine

6.2 Full Account Linking Sequence

6.3 Nonce Validation and Account Linking — Step-by-Step

The nonce mechanism prevents replay attacks and cryptographically binds each linking attempt to a specific Ring user.

Prerequisites

• Partner App Backend possesses an unclaimed OAuth token. After receiving the token, the partner retrieves the user's Account ID by calling GET https://api.amazonvision.com/v1/users/me (see Users API).
• Both Ring Backend and Partner App Backend share an HMAC signing key (K_hmac) exchanged during partner onboarding.
• Algorithm: HMAC-SHA256.

Nonce Technical Reference

The nonce mechanism uses HMAC-SHA256 with a time-bound validation window to ensure secure account linking.

Step 1: Ring Backend Generates Nonce and Redirects User

When the user clicks "Confirm" in the Ring App, Ring Backend generates a cryptographically signed nonce, transitions the integration status to awaiting, and redirects the user to the partner Account Link URL:

https://partner.example.com/ring/link?nonce=yT8jdW_nu2W4gR6FI-l8hkPpt_c9EAf4DJ9CTIcuM7c&time=1771130906289

Step 2: User Arrives at Partner App UI

The user lands on the Partner App UI login page with the nonce parameters in the URL.

Partner App Backend extracts time and nonce, then performs a freshness check:

VALIDATION_WINDOW_SECONDS = 600  # 10 minutes

current_time_ms = int(time.time() * 1000)
time_param_ms = int(request.args['time'])
time_delta_seconds = (current_time_ms - time_param_ms) / 1000

if time_delta_seconds > VALIDATION_WINDOW_SECONDS:
    raise Exception('Link request expired')
if time_delta_seconds < 0:
    raise Exception('Invalid timestamp: cannot be in the future')

Step 3: User Authenticates with Partner

The user signs in to the Partner App UI. The Partner App Backend authenticates the user and obtains their partner-side account information.

Why sign-in is mandatory:

1. Identifies the partner user — without sign-in, the partner has no verified way to know which user is performing the linking
2. Provides the account_identifier — the signed-in user's email (masked) is used when calling the App-Integrations API
3. Prevents blind token claiming — without explicit authentication, tokens would be claimed without user verification

Step 4: Partner Matches Nonce to Unclaimed Token

import hmac
import hashlib
import base64

def compute_nonce(time_param, account_id, hmac_key):
    """Compute nonce using the same algorithm as Ring Backend."""
    payload = f"{time_param}:{account_id}"
    mac = hmac.new(
        hmac_key.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).digest()
    return base64.urlsafe_b64encode(mac).rstrip(b'=').decode('utf-8')

def match_nonce_to_token(received_nonce, time_param, hmac_key):
    unclaimed_tokens = get_unclaimed_tokens()

    for token_record in unclaimed_tokens:
        account_id = token_record.account_id
        computed_nonce = compute_nonce(time_param, account_id, hmac_key)

        # Constant-time comparison to prevent timing attacks
        if hmac.compare_digest(computed_nonce, received_nonce):
            return token_record  # Match found

    return None  # No match

Step 5: Partner Claims Token and Calls App-Integrations API

POST https://api.amazonvision.com/v1/accounts/me/app-integrations
Authorization: Bearer <matched_ava_token>
Content-Type: application/json

{
  "account_identifier": "u***r@partner.example.com",
  "nonce": "yT8jdW_nu2W4gR6FI-l8hkPpt_c9EAf4DJ9CTIcuM7c"
}

See App Integrations API for full endpoint details.

Step 6: Ring Backend Verifies and Activates

Ring Backend verifies the nonce, transitions status to awaiting, activates device-level consents, and sends a confirmation email to the Ring user.

Step 7: Partner Calls PATCH to Complete Integration

PATCH https://api.amazonvision.com/v1/accounts/me/app-integrations
Authorization: Bearer <matched_ava_token>
Content-Type: application/json

{
  "status": "completed"
}

Security Considerations

The nonce-based account linking mechanism provides protection against common attack vectors including replay attacks, token interception, and unauthorized token claiming. The time-bound validation window and cryptographic verification ensure that only legitimate linking attempts succeed.

7. App Integration UX Flow

8. Accessing Devices

Once the integration reaches awaiting or completed status, the Partner App Backend can access authorized Ring devices through the Amazon Vision API.

See: Device Discovery · Live Video · Media Clips . Image Snapshots

8.1 Device Access Sequence

8.2 Authentication Header

All Amazon Vision API calls require a valid access token:

Authorization: Bearer <access_token>

If the token has expired, refresh it before making API calls. See Refresh Tokens.

9. Webhook Event Delivery

Ring Backend delivers real-time event notifications to the Partner App Backend via signed webhooks using HMAC-SHA256 signatures.

See: Notifications

9.1 Webhook Delivery Sequence

9.2 Event Types

10. Environment Configuration

Authentication

Ring utilizes OAuth 2.0 standard tokens for authentication to ensure secure communication with partner cloud services. The authentication system is based on an "account linking" mechanism that provides user-scoped authentication materials while maintaining customer awareness and control.

Overview

The authentication flow involves:

1. Account Linking: Users authenticate with partner systems
2. Token Exchange: Authorization codes are exchanged for access/refresh tokens
3. Token Management: Refresh tokens maintain long-term access

Key Components

• User-scoped tokens: Each token pair is associated with a specific Ring user
• Customer confirmation: Users must confirm the partner account before token release
• Webhook notifications: Tokens enable Ring to deliver signed webhook notifications to partners

Authentication Flow

sequenceDiagram
    participant User
    participant Ring
    participant Partner
    
    User->>Ring: Initiate integration
    Ring->>Partner: Redirect to login portal
    User->>Partner: Authenticate
    Partner->>Ring: Authorization code
    Ring->>Partner: Access & refresh tokens

Token Types

Access Tokens

• Used for API requests
• Short-lived (typically 4 hours)
• Include in Authorization: Bearer <token> header
• See Access Tokens for details

Refresh Tokens

• Used to obtain new access tokens
• Valid for approximately 30 days
• Must be refreshed proactively before expiry — an expired refresh token requires the user to re-link their account
• Critical for maintaining continuous access
• See Refresh Tokens for details

Quick Start: If You Already Have a Refresh Token

If you already have a refresh token (e.g., from a completed account linking flow) and need to start making API calls:

1. Obtain your client_id and client_secret — These are issued during partner onboarding.
2. Exchange the refresh token for an access token — Call POST https://oauth.ring.com/oauth/token with grant_type=refresh_token. See Refresh Token Exchange.
3. Use the access token in API requests — Include in the Authorization: Bearer <access_token> header.

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<your_refresh_token>&client_id=<your_client_id>&client_secret=<your_client_secret>

The response will include a new access_token (valid ~4 hours) and a new refresh_token. Store both securely.

Security Requirements

• All authentication materials are user-scoped
• Partners must use correct tokens for specific user data
• Token storage and handling must follow security best practices
• Regular token refresh is required to maintain access

Sub-pages

• Account Linking — OAuth account linking flow (one-way recommended)
• Refresh Tokens — Token refresh and management
• Access Tokens — Using access tokens in API requests

Account Linking

Account linking is the process by which Ring users connect their Ring account with a partner service. This process ensures user consent and establishes the authentication foundation for the integration.

Process Overview (Legacy Bidirectional Model)

Ring initiates account linking as part of the user journey to configure a partner integration. Users are redirected to a partner login portal where they authenticate and authorize the connection.

Partner Requirements

1. Login Portal with Ring Parameters

Partners must provide a login portal that accepts Ring parameters during redirect:

• redirect_uri: Allowlisted redirect URI back to Ring
• state: One-time use, time-bound state token for security

Example redirect:

https://partner.example.com/login?redirect_uri=https://ring.com/account/integrations/callback&state=abc123xyz

2. Authentication Material Exchange

After user authentication, partners must initiate the OAuth 2.0 authorization code flow:

Redirect format:

<redirect_uri>?state=<state>&code=<authorization_code>

3. Account Information API

Partners must provide an API endpoint that Ring can use to fetch user account information for confirmation:

GET https://api.partner.example.com/v1/integrations/ring
Authorization: Bearer <partner_token>

Response:
{
  "account_identifier": "xxx******xxx@example.com"
}

Requirements:

• Returns obfuscated account identifier (e.g., partial email)
• Enables user confirmation of linked account

4. Ring Credential Transfer API

Partners must be able to receive Ring's authorization code and exchange it for tokens:

POST https://oauth.ring.com/oauth/token

Request:
{
  "grant_type": "authorization_code",
  "code_verifier": "xxxxx",
  "client_id": "<partner_client_id>",
  "code": "<authorization_code>",
  "client_secret": "<secret>"
}

Response:
{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Important:

• Exchange must occur within 1 minute of receiving the code
• Client IDs and secrets are provided during onboarding
• PKCE (Proof Key for Code Exchange) is required for security

Account Linking (One-Way) — Recommended

For new integrations, Ring recommends the one-way account linking model. In this model, Ring releases OAuth credentials upfront and uses an HMAC nonce to cryptographically bind the redirect to a specific Ring user. Partners do not need to operate as OAuth servers.

How the Nonce Flow Works

1. Ring generates a nonce — HMAC-SHA256(K_hmac, "<timestamp_ms>:<account_id>"), encoded as URL-safe Base64 without padding
2. Ring redirects the user to the Partner Account Link URL with query parameters:

   https://partner.example.com/ring/link?nonce=yT8jdW_nu2W4gR6FI-l8hkPpt_c9EAf4DJ9CTIcuM7c&time=1771130906289
   

3. Partner validates timestamp freshness — rejects if older than 600 seconds (10 minutes)
4. User signs in to the partner service (mandatory) — the partner authenticates the user and obtains their partner-side identity
5. Partner matches the nonce — iterates unclaimed tokens, recomputes the HMAC for each using the stored Account ID and the received time, and performs a constant-time comparison
6. Partner claims the matched token and calls POST /v1/accounts/me/app-integrations with the nonce and the account_identifier derived from the signed-in user
7. Partner calls PATCH /v1/accounts/me/app-integrations with status: completed to finalize the integration — this step is mandatory

See App Integrations API for the verification endpoint details and Users API for Account ID retrieval.

Security Properties

Security Considerations

• State tokens prevent CSRF attacks (legacy bidirectional flow)
• Authorization codes are single-use and time-limited
• PKCE adds additional security layer (legacy bidirectional flow)
• HMAC nonces cryptographically bind linking attempts to specific users (one-way flow)
• Partner sign-in is mandatory during account linking
• All redirects must use allowlisted URIs

Refresh Tokens

Refresh tokens enable partners to maintain long-term access to Ring user data by obtaining new access tokens when the current ones expire.

Overview

• Access tokens have limited validity (typically 4 hours / 14400 seconds)
• Refresh tokens are valid for approximately 30 days
• Partners must refresh tokens proactively before they expire — an expired refresh token cannot be recovered and requires the Ring user to re-link their account through the Ring App
• Partners should store refresh tokens securely for continuous access

Quick Start: Exchanging a Refresh Token

HTTP Request

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<your_refresh_token>&client_id=<your_client_id>&client_secret=<your_client_secret>

Python Example

import requests

OAUTH_TOKEN_URL = "https://oauth.ring.com/oauth/token"

def exchange_refresh_token(refresh_token, client_id, client_secret):
    """Exchange a refresh token for a new access token."""
    response = requests.post(OAUTH_TOKEN_URL, data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret,
    })
    response.raise_for_status()
    tokens = response.json()

    # tokens contains: access_token, refresh_token, expires_in, token_type, scope
    return tokens

# Usage

tokens = exchange_refresh_token(
    refresh_token="your_refresh_token_here",
    client_id="your_client_id_here",
    client_secret="your_client_secret_here",
)

# Now use the access token for API calls
headers = {"Authorization": f"Bearer {tokens['access_token']}"}

JavaScript Example

async function exchangeRefreshToken(refreshToken, clientId, clientSecret) {
  const response = await fetch("https://oauth.ring.com/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      refresh_token: refreshToken,
      client_id: clientId,
      client_secret: clientSecret,
    }),
  });

  if (!response.ok) throw new Error(`Token exchange failed: ${response.status}`);
  return await response.json();
}

When to Refresh

Ring recommends refreshing tokens in these scenarios:

1. Proactive refresh: Based on the expires_in value from the token response
2. Reactive refresh: When receiving HTTP 401 responses from Ring endpoints

Refresh Token Exchange

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=<refresh_token>
client_id=<client_id>
client_secret=<client_secret>

Response:

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Implementation Best Practices

Token Storage

• Store refresh tokens securely (encrypted at rest)
• Associate tokens with the correct user accounts
• Implement proper access controls

Proactive Refresh Strategy

To prevent refresh token expiry, implement a background job that refreshes tokens before they expire:

import time

# Recommended: refresh tokens every 24 hours to maintain a healthy margin
REFRESH_INTERVAL_SECONDS = 86400  # 24 hours

def background_token_refresh():
    """Background job to proactively refresh all stored tokens."""
    for token_record in get_all_active_tokens():
        try:
            new_tokens = refresh_access_token(token_record.refresh_token)
            update_stored_tokens(token_record.account_id, new_tokens)
        except Exception as e:
            # Alert on refresh failures — may indicate approaching expiry
            alert_token_refresh_failure(token_record.account_id, e)

Security Considerations

• Refresh tokens are sensitive credentials
• Rotate refresh tokens regularly (they are updated with each exchange)
• Monitor for tokens approaching the 30-day expiry window
• Implement alerting for failed refresh attempts
• Implement rate limiting to prevent abuse

Related Documentation

• Access Tokens — How to use access tokens in API requests
• Account Linking — How the initial token exchange works

Access Tokens

Access tokens are the primary authentication material used to access Ring user data. They are user-scoped, meaning each token is associated with a specific Ring user account.

Token Characteristics

• Short-lived: Typically valid for 4 hours (14400 seconds)
• User-scoped: Each token provides access to one user's data
• Bearer tokens: Used in HTTP Authorization headers

Usage

Include access tokens in the Authorization header for all API requests:

Authorization: Bearer <access_token>

Example API Request

GET https://api.amazonvision.com/v1/devices
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Management

Expiration Handling

Access tokens include an expires_in field indicating their lifetime in seconds:

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Implementation Example

import time
import requests

class TokenManager:
    def __init__(self, access_token, refresh_token, expires_in):
        self.access_token = access_token
        self.refresh_token = refresh_token
        self.expires_at = time.time() + expires_in
    
    def get_valid_token(self):
        if time.time() >= self.expires_at - 300:  # Refresh 5 minutes early
            self.refresh_token_if_needed()
        return self.access_token
    
    def refresh_token_if_needed(self):
        # Implement refresh logic here
        pass
    
    def make_authenticated_request(self, url):
        headers = {
            'Authorization': f'Bearer {self.get_valid_token()}'
        }
        return requests.get(url, headers=headers)

Best Practices

1. Track expiration: Monitor token expiration times
2. Proactive refresh: Refresh tokens before they expire
3. Handle 401 responses: Implement automatic token refresh on authentication failures
4. Secure storage: Store tokens securely and associate with correct users

Account ID Retrieval

After receiving an access token, partners should call GET https://api.amazonvision.com/v1/users/me to retrieve the Ring user's Account ID. This Account ID is used for nonce matching during account linking and correlating webhook events. See Users API for details.

Scope and Permissions

Access tokens are scoped to specific permissions granted during the account linking process. The scope determines which Ring resources and operations the token can access.

Common scopes include:

• Device discovery and status
• Video streaming access
• Notification subscriptions
• Configuration reading

Security Considerations

• Never log or expose access tokens
• Use HTTPS for all API requests
• Implement proper token rotation
• Monitor for suspicious usage patterns
• Revoke tokens when users disconnect integrations

Related Documentation

• Refresh Tokens — How to refresh expired access tokens
• Account Linking — How the initial token exchange works

Users API

The Users API allows partners to retrieve basic profile information about the Ring user associated with their AVA access token. This endpoint returns the user's Account ID, name, email, and phone number.

Overview

Authentication

Requires a valid AVA access token:

Authorization: Bearer <ava_token>

See Access Tokens for details on obtaining and managing tokens.

GET — User Profile

Returns basic profile information for the Ring user associated with the provided AVA token. The me path parameter indicates the currently authenticated user.

Request

GET https://api.amazonvision.com/v1/users/me
Authorization: Bearer <ava_token>

No request body is required.

Response (200 OK)

{
  "data": {
    "type": "users",
    "id": "ava1.ring.account.XXXYYY",
    "attributes": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "johndoe@example.com",
      "phone_number": "18006561918"
    }
  }
}

Response Fields

Error Responses

Key Uses of Account ID

The Account ID (data.id) returned by this endpoint is used throughout the Ring integration:

1. Nonce matching during account linking — The Account ID is the binding identifier in the HMAC nonce. Ring computes the nonce as HMAC-SHA256(K_hmac, "<timestamp_ms>:<account_id>"). Partners call this endpoint for each unclaimed token at receipt time to store the Account ID, then use it to recompute and match the nonce during account linking. See Account Linking for details.

2. Webhook event association — The same Account ID appears in the meta.account_id field of all webhook notifications, allowing partners to associate events with the correct Ring user. See Notifications.

3. User management — Use the Account ID as the stable identifier for Ring users in your system. Avoid indexing on email or name as these may change.

Implementation Example

Basic Profile Retrieval

import requests

def get_user_profile(ava_token):
    """Get the Ring user profile for the given AVA token."""
    response = requests.get(
        "https://api.amazonvision.com/v1/users/me",
        headers={
            "Authorization": f"Bearer {ava_token}"
        }
    )

    if response.status_code == 200:
        user_data = response.json()['data']
        return {
            "account_id": user_data['id'],
            "first_name": user_data['attributes']['first_name'],
            "last_name": user_data['attributes']['last_name'],
            "email": user_data['attributes']['email'],
            "phone_number": user_data['attributes']['phone_number']
        }
    elif response.status_code == 403:
        raise PermissionError("Invalid or expired token")
    elif response.status_code == 404:
        raise LookupError("User not found")
    else:
        response.raise_for_status()

Store Account ID at Token Receipt

Call this endpoint immediately after receiving an AVA token to store the Account ID for later use in nonce matching and event correlation:

def on_token_received(ava_token, refresh_token):
    """Called when a new AVA token is received during OAuth exchange."""
    profile = get_user_profile(ava_token)
    account_id = profile['account_id']

    token_store.save(
        access_token=ava_token,
        refresh_token=refresh_token,
        account_id=account_id,
        status="unclaimed"
    )

    return account_id

Best Practices

1. Call immediately after token exchange — Retrieve the Account ID as soon as you receive the AVA token so it's available for nonce matching
2. Use Account ID as primary identifier — Do not index on email or name, as users can change these at any time
3. Cache profile data carefully — User profile data may change; re-fetch periodically if displaying user info
4. Handle token expiration — If you get a 403, refresh the token and retry
5. Privacy compliance — Handle user personal information according to your privacy policy and Ring's partner agreements

App Integration

The App Integrations API allows partners to manage the lifecycle of their Ring AppStore integration. Partners use these endpoints to confirm account linking, update integration configuration status, and manage the association between their users and Ring users.

Overview

The App Integrations API provides two operations on a single endpoint. Both calls are required to complete the integration — POST to confirm the account link, then PATCH to finalize the integration status:

Both endpoints:

• Require a valid AVA access token in the Authorization: Bearer header
• Derive the Ring user identity from the token (no explicit user ID needed)
• Use standard JSON request/response format

Authentication

All requests require a valid AVA access token obtained through the OAuth token exchange flow:

Authorization: Bearer <ava_token>

See Access Tokens for details.

POST — Confirm Account Link

Called by the Partner App Backend after a Ring user has authenticated with the partner service. This endpoint verifies the nonce from the account linking redirect and establishes the link between the Ring user and the partner account.

When to Call

Call this endpoint after:

1. The Ring user has been redirected to your Account Link URL with time and nonce query parameters
2. The user has signed in to your partner service (mandatory)
3. You have matched the nonce to the correct unclaimed AVA token

Request

POST https://api.amazonvision.com/v1/accounts/me/app-integrations
Authorization: Bearer <ava_token>
Content-Type: application/json

{
  "account_identifier": "u***r@partner.example.com",
  "nonce": "<nonce_value>"
}

Request Fields

Response (200 OK)

{
  "status": "awaiting"
}

Error Responses

Side Effects

When this endpoint is called successfully:

• The integration status transitions to awaiting
• Device-level consents are activated — the partner can now access authorized devices
• Ring sends a confirmation email to the Ring user

Implementation Example

import requests

def verify_account_link(ava_token, account_identifier, nonce):
    """Verify the account link with Ring after user authenticates."""
    response = requests.post(
        "https://api.amazonvision.com/v1/accounts/me/app-integrations",
        headers={
            "Authorization": f"Bearer {ava_token}",
            "Content-Type": "application/json"
        },
        json={
            "account_identifier": account_identifier,
            "nonce": nonce
        }
    )

    if response.status_code == 200:
        return response.json()  # {"status": "awaiting"}
    elif response.status_code == 400:
        raise ValueError(f"Verification failed: {response.json()}")
    elif response.status_code == 404:
        raise LookupError("Integration not found for this token")
    else:
        response.raise_for_status()

PATCH — Update Integration Status

Called by the Partner App Backend to update the integration status. This call is mandatory after the POST nonce validation to finalize the integration.

When to Call

• During initial integration (required): After POST succeeds — call PATCH with status: completed
• During ongoing operations (as needed): To pause configuration or update account_identifier

Request

PATCH https://api.amazonvision.com/v1/accounts/me/app-integrations
Authorization: Bearer <ava_token>
Content-Type: application/json

{
  "account_identifier": "u***r@partner.example.com",
  "status": "completed"
}

Request Fields

At least one field must be provided.

Response (200 OK)

{
  "account_identifier": "u***r@partner.example.com",
  "status": "completed",
  "updated_at": "2026-02-03T00:35:00Z"
}

Error Responses

Integration Status Lifecycle

Required integration flow:

1. POST with nonce → status becomes awaiting
2. PATCH with status: completed → status becomes completed (mandatory)

Complete Integration Example

import requests

def complete_integration(ava_token, account_identifier, nonce):
    """Complete the full integration: POST nonce verification, then PATCH to completed."""

    # Step 1: POST — Verify the nonce and confirm account link
    post_response = requests.post(
        "https://api.amazonvision.com/v1/accounts/me/app-integrations",
        headers={
            "Authorization": f"Bearer {ava_token}",
            "Content-Type": "application/json"
        },
        json={
            "account_identifier": account_identifier,
            "nonce": nonce
        }
    )

    if post_response.status_code != 200:
        raise ValueError(f"POST nonce verification failed: {post_response.json()}")

    # Step 2: PATCH — Update status to completed (REQUIRED)
    patch_response = requests.patch(
        "https://api.amazonvision.com/v1/accounts/me/app-integrations",
        headers={
            "Authorization": f"Bearer {ava_token}",
            "Content-Type": "application/json"
        },
        json={
            "status": "completed"
        }
    )

    if patch_response.status_code != 200:
        raise ValueError(f"PATCH status update failed: {patch_response.json()}")

    return patch_response.json()

Best Practices

1. Call POST immediately after nonce matching — The verification window is time-limited
2. Call PATCH after POST succeeds — Mandatory to finalize the integration
3. Mask account identifiers — Use obfuscated identifiers to protect user privacy
4. Update account_identifier on changes — If the user updates their email, call PATCH
5. Handle errors gracefully — Implement retry logic for transient failures
6. Use the correct AVA token — Must be associated with the specific Ring user being linked
7. Require user sign-in before processing the nonce — The account_identifier must come from an authenticated partner session

Device Discovery

After obtaining customer authentication materials, partners can access Ring's public API to discover and interact with shared devices. Device discovery is the entry point for accessing Ring resources.

Overview

Device discovery follows the JSON:API Specification and provides:

• Basic device information and identification
• Device capabilities and supported features
• Current device status and connectivity
• Location information (coarse-grained)
• User configurations and settings

Basic Device Discovery

Retrieve a list of devices accessible to the authenticated user:

GET https://api.amazonvision.com/v1/devices
Authorization: Bearer <access_token>

Response Structure

{
  "meta": {
    "time": "2026-02-14T22:57:16Z"
  },
  "data": [
    {
      "type": "devices",
      "id": "ava1.ring.device.XXXYYY",
      "attributes": {
        "name": "Front Door Camera"
      },
      "relationships": {
        "status": {
          "data": {
            "type": "device-status",
            "id": "ava1.ring.device.status.XXXYYY"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/status"
          }
        },
        "capabilities": {
          "data": {
            "type": "device-capabilities",
            "id": "ava1.ring.device.capabilities.XXXYYY"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/capabilities"
          }
        },
        "configurations": {
          "data": {
            "type": "device-configurations",
            "id": "ava1.ring.device.configurations.XXXYYY"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/configurations"
          }
        },
        "location": {
          "data": {
            "type": "locations",
            "id": "5ecd04ff-3d93-4a6e-80e4-035f735a58e4"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/location"
          }
        }
      }
    }
  ]
}

Response Fields

Including Related Data

Use the include query parameter to fetch related data in a single request:

GET https://api.amazonvision.com/v1/devices?include=status,capabilities
Authorization: Bearer <access_token>

Response with Included Data (Compound Document)

When using ?include=status,capabilities, the related resources are returned in a top-level included array. Match resources using the type + id pair from relationships.{rel}.data to the corresponding entry in included:

{
  "meta": {
    "time": "2026-02-14T22:57:16Z"
  },
  "data": [
    {
      "type": "devices",
      "id": "ava1.ring.device.XXXYYY",
      "attributes": {
        "name": "Office"
      },
      "relationships": {
        "status": {
          "data": { "type": "device-status", "id": "ava1.ring.device.status.XXXYYY" },
          "links": { "related": "/v1/devices/ava1.ring.device.XXXYYY/status" }
        },
        "capabilities": {
          "data": { "type": "device-capabilities", "id": "ava1.ring.device.capabilities.XXXYYY" },
          "links": { "related": "/v1/devices/ava1.ring.device.XXXYYY/capabilities" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "device-status",
      "id": "ava1.ring.device.status.XXXYYY",
      "attributes": {
        "online": true
      }
    },
    {
      "type": "device-capabilities",
      "id": "ava1.ring.device.capabilities.XXXYYY",
      "attributes": {
        "video": {
          "configurations": ["resolution_mode"],
          "codecs": ["AVC"],
          "ratio": "16:9",
          "max_resolution": 1080,
          "supported_resolutions": [1080]
        },
        "motion_detection": {
          "configurations": ["enabled", "motion_zones"]
        },
        "image_enhancements": {
          "configurations": ["color_night_vision", "hdr", "ir_led_night_vision", "privacy_zones"]
        }
      }
    }
  ]
}

Included Resource Fields

Device Relationships

Each device provides relationships to:

• Status: Online/offline state and connectivity — see Status
• Capabilities: Supported features and hardware specs — see Capabilities
• Location: Coarse geographic information — see Locations
• Configurations: User settings and preferences — see Configurations

JSON:API Compliance

The device discovery API follows JSON:API specifications:

• Consistent resource structure with type, id, attributes, relationships
• Resource linkage via data objects (type + id) in relationships
• Compound documents via include parameter with top-level included array
• Relationship links for individual resource fetching
• Extensible attribute model for future enhancements

Rate Limiting

• Respect rate limits (don't exceed 100 TPS)
• Implement exponential backoff for retries
• Cache device information when appropriate

Sub-pages

• Capabilities — Device hardware features and supported functionality
• Status — Real-time device availability and connectivity
• Locations — Coarse geographic information for compliance
• Configurations — User settings, motion zones, and privacy zones

Capabilities

Device capabilities provide information about the hardware features and supported functionality of Ring devices. This information helps partners understand what operations are available for each device.

Accessing Capabilities

Capabilities can be retrieved in two ways:

1. During device discovery using the include parameter:

   GET https://api.amazonvision.com/v1/devices?include=capabilities
   Authorization: Bearer <access_token>
   

2. Individual device capabilities:

   GET https://api.amazonvision.com/v1/devices/{device_id}/capabilities
   Authorization: Bearer <access_token>
   

Response Structure

{
  "meta": {
    "time": "2025-07-07T10:30:00Z"
  },
  "data": {
    "id": "xxxyyy.capabilities",
    "type": "device-capabilities",
    "attributes": {
      "video": {
        "configurations": ["resolution_mode"],
        "codecs": ["HEVC"],
        "ratio": "16:9",
        "max_resolution": 2160,
        "supported_resolutions": [2160]
      },
      "motion_detection": {
        "configurations": ["enabled", "motion_zones"]
      },
      "image_enhancements": {
        "configurations": [
          "color_night_vision",
          "hdr",
          "ir_led_night_vision",
          "auto_zoom_track",
          "privacy_zones"
        ]
      }
    },
    "relationships": {
      "configurations": {
        "links": {
          "related": "/v1/devices/xxxyyy/configurations"
        }
      }
    }
  }
}

Capability Types

Video Capabilities

• codecs: Supported video codecs (HEVC, AVC)
• ratio: Video aspect ratio
• max_resolution: Maximum supported resolution
• supported_resolutions: Array of available resolutions
• configurations: Related configuration options

Motion Detection

• configurations: Available motion detection settings
• Typically includes motion zones and enable/disable options

Image Enhancements

• color_night_vision: Color night vision support
• hdr: High Dynamic Range support
• ir_led_night_vision: Infrared LED night vision
• auto_zoom_track: Automatic zoom and tracking
• privacy_zones: Privacy zone configuration

Important Notes

• Optional capabilities: Not all devices support all capabilities
• Device variation: Capabilities vary significantly between Ring device models
• Configuration relationship: Each capability lists its related configuration options
• Future extensibility: Additional capabilities may be added over time

Using Capability Information

Partners should:

1. Check for capability existence before attempting related operations
2. Use the configurations array to understand available settings
3. Handle missing capabilities gracefully
4. Cache capability information as it rarely changes

Example Usage

def check_video_capabilities(device_capabilities):
    video_caps = device_capabilities.get('attributes', {}).get('video')
    if video_caps:
        max_res = video_caps.get('max_resolution', 1080)
        codecs = video_caps.get('codecs', ['AVC'])
        return {
            'supports_4k': max_res >= 2160,
            'supports_hevc': 'HEVC' in codecs
        }
    return {'supports_4k': False, 'supports_hevc': False}

Status

Device status provides real-time information about device availability and connectivity. This is essential for determining whether devices can respond to requests or stream video.

Accessing Device Status

Status information can be retrieved in two ways:

1. During device discovery using the include parameter:

   GET https://api.amazonvision.com/v1/devices?include=status
   Authorization: Bearer <access_token>
   

2. Individual device status:

   GET https://api.amazonvision.com/v1/devices/{device_id}/status
   Authorization: Bearer <access_token>
   

Response Structure

{
  "meta": {
    "time": "2025-07-07T10:30:00Z"
  },
  "data": {
    "type": "device-status",
    "id": "xxxyyy.status",
    "attributes": {
      "online": true
    }
  }
}

Status Attributes

Online Status

• online: Boolean indicating if the device is currently connected
• Primary indicator for device availability
• Essential for determining if live streaming or commands will work

Usage Patterns

Checking Device Availability

def is_device_available(device_status):
    return device_status.get('attributes', {}).get('online', False)

def can_stream_video(device_id, device_status):
    if is_device_available(device_status):
        return True
    else:
        print(f"Device {device_id} is offline - streaming not available")
        return False

Best Practices

1. Check before operations: Always verify device is online before attempting video streaming or configuration changes
2. Handle offline gracefully: Provide appropriate user feedback when devices are offline
3. Cache appropriately: Status can change frequently, so don't cache for extended periods
4. Monitor status changes: Consider implementing status monitoring for critical operations

Error Scenarios

When devices are offline:

• Live video streaming will fail
• Configuration changes may not be applied immediately
• Motion detection may not trigger notifications
• Historical video may still be available depending on cloud storage

Locations

Device location information provides coarse, non-specific geographic data about where Ring devices are installed. This information may be required for determining local legal compliance or regional feature availability.

Accessing Location Data

Location information can be retrieved in two ways:

1. During device discovery using the include parameter:

   GET https://api.amazonvision.com/v1/devices?include=location
   Authorization: Bearer <access_token>
   

2. Individual device location:

   GET https://api.amazonvision.com/v1/devices/{device_id}/location
   Authorization: Bearer <access_token>
   

Response Structure

{
  "meta": {
    "time": "2025-07-07T10:30:00Z"
  },
  "data": {
    "type": "locations",
    "id": "zzzzzz",
    "attributes": {
      "country": "US",
      "state": "GA"
    }
  }
}

Location Attributes

Country

• country: ISO country code (e.g., "US", "CA", "GB")
• Always provided when location data is available
• Primary identifier for regional compliance

State/Province

• state: State or province code (e.g., "GA", "CA", "ON")
• Provided for devices in the United States when available
• Should be treated as optional and non-guaranteed
• May not be available for all countries

Privacy and Granularity

Ring provides intentionally coarse location information to protect user privacy:

• No precise coordinates: Exact addresses or GPS coordinates are never provided
• Country-level minimum: At minimum, country information is provided
• State-level maximum: For supported regions, state/province may be included
• No city-level data: Specific cities or postal codes are not provided

Use Cases

Legal Compliance

def check_regional_compliance(device_location):
    country = device_location.get('attributes', {}).get('country')
    state = device_location.get('attributes', {}).get('state')
    
    if country == 'US':
        if state in ['CA', 'IL']:  # States with specific privacy laws
            return apply_enhanced_privacy_controls()
    elif country in ['GB', 'DE', 'FR']:
        return apply_gdpr_controls()
    
    return apply_default_controls()

Important Considerations

1. Optional data: Location information may not be available for all devices
2. Privacy first: Location data is intentionally limited to protect user privacy
3. Compliance focus: Primary use case is legal and regulatory compliance
4. No tracking: This data should not be used for user tracking or analytics
5. Static nature: Device locations typically don't change frequently

Configurations

Device configurations provide details about user-specified settings that may affect partner processing of video content and device behavior. These settings are particularly important for motion detection and privacy considerations.

Accessing Configuration Data

Configuration information can be retrieved in two ways:

1. During device discovery using the include parameter:

   GET https://api.amazonvision.com/v1/devices?include=configurations
   Authorization: Bearer <access_token>
   

2. Individual device configurations:

   GET https://api.amazonvision.com/v1/devices/{device_id}/configurations
   Authorization: Bearer <access_token>
   

Response Structure

{
  "meta": {
    "time": "2026-02-14T23:37:48Z"
  },
  "data": {
    "type": "device-configurations",
    "id": "ava1.ring.device.configurations.XXXYYY",
    "attributes": {
      "motion_detection": {
        "enabled": "on",
        "motion_zones": [
          {
            "id": "a9d225a6-3122-4f4d-a933-0c24e53cc535",
            "vertices": [
              {"x": 0, "y": 0.2},
              {"x": 0.5, "y": 0.2},
              {"x": 1, "y": 0.2},
              {"x": 1, "y": 0.6},
              {"x": 1, "y": 1},
              {"x": 0.5, "y": 1},
              {"x": 0, "y": 1},
              {"x": 0, "y": 0.6}
            ]
          }
        ]
      },
      "image_enhancements": {
        "color_night_vision": "off",
        "hdr": "off",
        "ir_led_night_vision": "off",
        "auto_zoom_track": "off",
        "privacy_zones": []
      }
    }
  }
}

Configuration Categories

Motion Detection

• enabled: Motion detection on/off status ("on" or "off")
• motion_zones: Array of defined motion detection areas
  • Each zone has a UUID id and vertices array
  • Vertices define the polygon boundaries of the detection zone

Image Enhancements

• color_night_vision: Color night vision setting ("on" or "off")
• hdr: High Dynamic Range setting ("on" or "off")
• ir_led_night_vision: Infrared LED night vision setting ("on" or "off")
• auto_zoom_track: Automatic zoom and tracking setting ("on" or "off")
• privacy_zones: Array of privacy zones that should be obscured (same structure as motion zones)

Zone Coordinate System

Zones use a normalized coordinate system where all values are in the range 0.0 to 1.0:

• Origin: Top-left corner (0, 0)
• X-axis: 0.0 = left edge, 1.0 = right edge
• Y-axis: 0.0 = top edge, 1.0 = bottom edge
• Vertices: Define polygon boundaries as ordered points

To convert to pixel coordinates, multiply by the frame dimensions:

pixel_x = vertex['x'] * frame_width
pixel_y = vertex['y'] * frame_height

Impact on Partner Operations

Motion Detection Settings

def should_process_motion_events(device_config):
    motion_config = device_config.get('attributes', {}).get('motion_detection', {})
    return motion_config.get('enabled') == 'on'

def get_motion_zones(device_config):
    motion_config = device_config.get('attributes', {}).get('motion_detection', {})
    return motion_config.get('motion_zones', [])

Privacy Zone Handling

def get_privacy_zones(device_config):
    image_config = device_config.get('attributes', {}).get('image_enhancements', {})
    return image_config.get('privacy_zones', [])

def should_obscure_regions(device_config):
    privacy_zones = get_privacy_zones(device_config)
    return len(privacy_zones) > 0

Example Zone Processing

def point_in_polygon(point, vertices):
    """Check if a normalized point (0-1 range) is inside a polygon."""
    x, y = point
    n = len(vertices)
    inside = False
    
    p1x, p1y = vertices[0]['x'], vertices[0]['y']
    for i in range(1, n + 1):
        p2x, p2y = vertices[i % n]['x'], vertices[i % n]['y']
        if y > min(p1y, p2y):
            if y <= max(p1y, p2y):
                if x <= max(p1x, p2x):
                    if p1y != p2y:
                        xinters = (y - p1y) * (p2x - p1x) / (p2y - p1y) + p1x
                    if p1x == p2x or x <= xinters:
                        inside = not inside
        p1x, p1y = p2x, p2y
    
    return inside

Best Practices

1. Respect privacy zones: Always obscure or avoid processing areas marked as privacy zones
2. Check motion settings: Verify motion detection is enabled before expecting motion events
3. Handle missing configs: Not all devices will have all configuration options
4. Zone processing: Implement proper polygon intersection algorithms for zone handling
5. Configuration changes: Be prepared for configurations to change over time
6. Numeric type safety: Always handle vertex coordinates as Number (not Double or Integer) to avoid type cast errors

Notifications

Ring provides real-time notifications to partners through webhook-based callbacks. This enables partners to receive timely updates about device events, changes, and user actions.

Overview

The notification system uses:

• HTTP POST webhooks to partner endpoints
• HMAC-SHA256 signature in the X-Signature header for message authenticity
• JSON:API structure for consistent payload format
• Event-driven architecture for real-time updates
• Account ID in meta for user association

Webhook Endpoint Requirements

Before receiving webhooks, your endpoint must meet the following requirements:

Webhook Authentication & Verification

HMAC-SHA256 Signature Verification

All webhook requests from Ring include an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature using the HMAC signing key issued with their partner credentials before processing any webhook payload:

POST https://api.partner.example.com/webhooks/ring
X-Signature: sha256=<hmac_signature>
Content-Type: application/json

Signature Verification

import hmac
import hashlib

def verify_webhook_signature(signing_key, raw_body, received_signature):
    """Verify the HMAC-SHA256 signature of a Ring webhook."""
    expected = hmac.new(
        signing_key.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    received = received_signature.removeprefix("sha256=")

    # Constant-time comparison to prevent timing attacks
    return hmac.compare_digest(expected, received)

Webhook v1.1 Payload Structure

All Ring webhooks follow the v1.1 payload format with account_id in the meta section:

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-13T13:39:57.200155525Z",
    "request_id": "2ad45ade-1818-4154-813b-afdd8bcd8085",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_<event_type>_<timestamp>",
    "type": "<event_type>",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1770989995231
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

Meta Fields

• version: Always 1.1 for the current webhook specification
• time: ISO 8601 timestamp when Ring sent the webhook
• request_id: Unique identifier for this webhook request (use for idempotency)
• account_id: The Account ID of the Ring user associated with this event

Event Types

Ring supports the following webhook event types:

Webhook Response Handling

Your endpoint must respond with an appropriate HTTP status code:

Retry Logic

Ring implements automatic retry logic for failed webhook deliveries (5xx responses and timeouts):

Retry Schedule

• Maximum retry attempts: 6 retries (7 total attempts including the initial delivery)
• Dead letter queue: After all retries are exhausted, the event is moved to a dead letter queue. Events are retained for 72 hours. Partners can request a replay of dead-lettered events by contacting their Ring integration representative.

Implementation Best Practices

Webhook Handler Example

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

SIGNING_KEY = "your_hmac_signing_key"

@app.route('/webhook/ring', methods=['POST'])
def handle_ring_webhook():
    # Verify HMAC signature
    signature = request.headers.get('X-Signature', '')
    if not verify_webhook_signature(SIGNING_KEY, request.data, signature):
        return jsonify({'error': 'Invalid signature'}), 401

    # Parse payload
    try:
        payload = request.get_json()
        event_type = payload['data']['type']
        account_id = payload['meta']['account_id']

        # Route to appropriate handler
        if event_type == 'motion_detected':
            handle_motion_detection(payload)
        elif event_type == 'button_press':
            handle_button_press(payload)
        elif event_type == 'device_added':
            handle_device_addition(payload)
        elif event_type == 'device_removed':
            handle_device_removal(payload)
        elif event_type == 'device_online':
            handle_device_online(payload)
        elif event_type == 'device_offline':
            handle_device_offline(payload)
        else:
            return jsonify({'error': 'Unknown event type'}), 400

        return jsonify({'status': 'processed'}), 200

    except Exception as e:
        log_error(f"Webhook processing failed: {e}")
        return jsonify({'error': 'Processing failed'}), 500

Idempotency Handling

def handle_webhook_with_idempotency(payload):
    request_id = payload['meta']['request_id']

    if is_already_processed(request_id):
        return {'status': 'already_processed'}

    result = process_webhook(payload)
    mark_as_processed(request_id)
    return result

Common Mistakes

Security Considerations

1. Verify HMAC signature: Always validate the X-Signature header
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Validate payload: Check request structure and required fields
4. Idempotency: Handle duplicate deliveries gracefully using request_id
5. Rate limiting: Implement appropriate rate limiting on webhook endpoints
6. Respond quickly: Return HTTP 200 within 5 seconds

Motion Detection

Motion detection notifications are sent when Ring devices detect movement in their field of view. These real-time notifications enable partners to respond immediately to motion events.

Webhook Delivery

Ring delivers all webhook notifications with an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature before processing the payload. See Notifications for signature verification details.

Webhook Payload

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-13T13:39:57.200155525Z",
    "request_id": "2ad45ade-1818-4154-813b-afdd8bcd8085",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_human_<timestamp>",
    "type": "motion_detected",
    "subType": "human",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1770989995231
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

Payload Fields

Meta Information

• version: Webhook payload version (1.1 includes account_id)
• time: ISO 8601 timestamp when Ring sent the webhook
• request_id: Unique identifier for this webhook request (use for idempotency)
• account_id: The Account ID of the Ring user associated with this event

Event Data

• id: Unique identifier for this specific motion event (format: <device_id>_<subType>_<timestamp>)
• type: Always motion_detected for motion events
• subType: Classification of the motion detected (e.g., human)
• source: Device ID that detected the motion
• source_type: Always devices for device-originated events
• timestamp: Epoch milliseconds when motion was detected

Valid subType values:

Processing Motion Events

def handle_motion_detection(payload):
    device_id = payload['data']['attributes']['source']
    account_id = payload['meta']['account_id']
    motion_timestamp = payload['data']['attributes']['timestamp']
    event_id = payload['data']['id']
    sub_type = payload['data'].get('subType', 'unknown')
    
    log_motion_event(device_id, account_id, motion_timestamp, event_id, sub_type)
    trigger_motion_response(device_id, account_id, motion_timestamp, sub_type)
    
    return {'status': 'processed'}

Best Practices

1. Verify HMAC signature: Always verify the X-Signature header before processing
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Handle subType: Use subType (e.g., human) to differentiate motion classifications
4. Handle duplicates: Implement idempotency using request_id or event id
5. Respond quickly: Return HTTP 200 within 5 seconds to avoid timeout
6. Respect configuration: Check device motion detection settings

Button Press

Button press notifications are sent when a Ring doorbell button is pressed. These real-time notifications enable partners to respond immediately to doorbell press events.

Webhook Delivery

Ring delivers all webhook notifications with an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature before processing the payload. See Notifications for signature verification details.

Webhook Payload

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-14T00:02:53.027052438Z",
    "request_id": "c83081fc-2f1b-4cb7-8b18-b18a318b8bab",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_button_press_<timestamp>",
    "type": "button_press",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1771027372393
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

Payload Fields

Meta Information

• version: Webhook payload version (1.1 includes account_id)
• time: ISO 8601 timestamp when Ring sent the webhook
• request_id: Unique identifier for this webhook request (use for idempotency)
• account_id: The Account ID of the Ring user associated with this event

Event Data

• id: Unique identifier (format: <device_id>_button_press_<timestamp>)
• type: Always button_press for doorbell press events
• source: Device ID of the doorbell that was pressed
• source_type: Always devices
• timestamp: Epoch milliseconds when the button was pressed

When Button Press Occurs

Button press notifications are triggered when:

• A visitor presses the Ring doorbell button
• The doorbell hardware button is physically activated

Processing Button Press Events

def handle_button_press(payload):
    device_id = payload['data']['attributes']['source']
    account_id = payload['meta']['account_id']
    press_timestamp = payload['data']['attributes']['timestamp']
    event_id = payload['data']['id']
    
    log_button_press(device_id, account_id, press_timestamp, event_id)
    trigger_doorbell_response(device_id, account_id, press_timestamp)
    
    return {'status': 'processed'}

Best Practices

1. Verify HMAC signature: Always verify the X-Signature header before processing
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Handle duplicates: Implement idempotency using request_id or event id
4. Respond quickly: Return HTTP 200 within 5 seconds to avoid timeout
5. Trigger video: Consider initiating a live video session after button press for visual verification

Device Addition

Device addition notifications are sent when a new Ring device becomes available for partner access. This occurs when users add devices to their account or grant additional permissions to the partner integration.

Webhook Delivery

Ring delivers all webhook notifications with an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature before processing the payload. See Notifications for signature verification details.

Webhook Payload

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-13T12:20:20.935994571Z",
    "request_id": "216c97be-4d57-45c1-a9f0-28c9f5442e8c",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_device_added_<timestamp>",
    "type": "device_added",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1770985219558
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

When Device Addition Occurs

Device addition notifications are triggered when:

• User installs a new Ring device and grants partner access
• User modifies integration settings to include additional devices
• Device permissions are restored after being temporarily revoked

Processing Device Addition

def handle_device_addition(payload):
    device_id = payload['data']['attributes']['source']
    account_id = payload['meta']['account_id']
    
    # Fetch full device information
    device_info = fetch_device_details(device_id)
    
    if device_info:
        store_new_device(device_info, account_id)
        setup_device_monitoring(device_id)
        return {'status': 'device_added'}
    else:
        return {'status': 'error', 'message': 'Failed to fetch device details'}

Best Practices

1. Verify HMAC signature: Always verify the X-Signature header before processing
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Immediate processing: Process device additions promptly to enable functionality
4. Fetch device info: Call GET /v1/devices/{id}?include=capabilities,status after receiving the notification
5. Handle duplicates: Implement idempotency using request_id or event id
6. Respond quickly: Return HTTP 200 within 5 seconds to avoid timeout

Device Removal

Device removal notifications are sent when a partner loses access to a Ring device. This occurs when users revoke permissions, remove devices, or modify their integration settings.

Webhook Delivery

Ring delivers all webhook notifications with an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature before processing the payload. See Notifications for signature verification details.

Webhook Payload

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-13T19:28:04.020279817Z",
    "request_id": "668b822c-266b-43c4-a1f0-6045bc5f3b1c",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_device_removed_<timestamp>",
    "type": "device_removed",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1771010883164
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

When Device Removal Occurs

Device removal notifications are triggered when:

• User explicitly removes device from partner integration
• User deletes the device from their Ring account
• User revokes partner access permissions
• Device is permanently offline or decommissioned
• Integration is disconnected or disabled

Processing Device Removal

def handle_device_removal(payload):
    device_id = payload['data']['attributes']['source']
    account_id = payload['meta']['account_id']
    removal_timestamp = payload['data']['attributes']['timestamp']
    
    # Stop active streaming sessions
    terminate_active_streams(device_id)
    
    # Cancel scheduled operations
    cancel_scheduled_operations(device_id)
    
    # Clean up stored data
    cleanup_device_resources(device_id)
    
    # Update device status in partner system
    mark_device_removed(device_id, account_id, removal_timestamp)
    
    return {'status': 'device_removed'}

Post-Removal Behavior

After device removal:

• All API requests for the device will return 404 errors
• Active streaming sessions are terminated
• Scheduled operations are cancelled
• Historical data may be preserved for audit purposes

Best Practices

1. Verify HMAC signature: Always verify the X-Signature header before processing
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Immediate cleanup: Process removal notifications promptly to free resources
4. Graceful termination: Close active sessions and operations cleanly
5. Data preservation: Archive important data before cleanup
6. User communication: Inform users about device removal
7. Audit logging: Log all removal events for compliance
8. Idempotency: Handle duplicate removal notifications safely

Device Online

Device online notifications are sent when a Ring device comes online and becomes available for interaction. These real-time notifications enable partners to know when devices are reachable for streaming, configuration, or other operations.

Webhook Delivery

Ring delivers all webhook notifications with an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature before processing the payload. See Notifications for signature verification details.

Webhook Payload

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-13T23:32:51.234231900Z",
    "request_id": "ab058f6f-8edd-4e92-9796-956ddc4d739d",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_device_online_<timestamp>",
    "type": "device_online",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1771025567000
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

When Device Online Occurs

Device online notifications are triggered when:

• A device reconnects to the network after being offline
• A device powers on after being powered off
• A device restores connectivity after a network interruption

Processing Device Online Events

def handle_device_online(payload):
    device_id = payload['data']['attributes']['source']
    account_id = payload['meta']['account_id']
    online_timestamp = payload['data']['attributes']['timestamp']
    
    update_device_status(device_id, account_id, 'online', online_timestamp)
    resume_device_operations(device_id)
    
    return {'status': 'processed'}

Best Practices

1. Verify HMAC signature: Always verify the X-Signature header before processing
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Update status tracking: Maintain device online/offline status in your system
4. Resume operations: Re-enable any features that were paused while the device was offline
5. Handle duplicates: Implement idempotency using request_id or event id
6. Respond quickly: Return HTTP 200 within 5 seconds to avoid timeout

Device Offline

Device offline notifications are sent when a Ring device goes offline and is no longer reachable. These real-time notifications enable partners to handle device unavailability gracefully and inform users.

Webhook Delivery

Ring delivers all webhook notifications with an HMAC-SHA256 signature in the X-Signature header. Partners must verify this signature before processing the payload. See Notifications for signature verification details.

Webhook Payload

{
  "meta": {
    "version": "1.1",
    "time": "2026-02-13T23:26:49.710448203Z",
    "request_id": "343385ae-1de8-4b29-85aa-07bd4b7112fd",
    "account_id": "ava1.ring.account.XXXYYY"
  },
  "data": {
    "id": "<device_id>_device_offline_<timestamp>",
    "type": "device_offline",
    "attributes": {
      "source": "<device_id>",
      "source_type": "devices",
      "timestamp": 1771025206000
    },
    "relationships": {
      "devices": {
        "links": {
          "self": "/v1/devices/<device_id>"
        }
      }
    }
  }
}

When Device Offline Occurs

Device offline notifications are triggered when:

• A device loses network connectivity
• A device powers off or runs out of battery
• A device experiences a hardware or firmware issue preventing communication

Processing Device Offline Events

def handle_device_offline(payload):
    device_id = payload['data']['attributes']['source']
    account_id = payload['meta']['account_id']
    offline_timestamp = payload['data']['attributes']['timestamp']
    
    update_device_status(device_id, account_id, 'offline', offline_timestamp)
    terminate_active_streams(device_id)
    pause_device_operations(device_id)
    
    return {'status': 'processed'}

Best Practices

1. Verify HMAC signature: Always verify the X-Signature header before processing
2. Use account_id: Associate events with the correct Ring user via meta.account_id
3. Update status tracking: Mark the device as offline in your system
4. Terminate active sessions: Close any active video streams for the device
5. Pause operations: Suspend scheduled operations until the device comes back online
6. Handle duplicates: Implement idempotency using request_id or event id
7. Respond quickly: Return HTTP 200 within 5 seconds to avoid timeout

Live Video

Ring provides live video streaming through WebRTC connectivity using the WHEP (WebRTC HTTP Egress Protocol) standard. This enables low-latency video streaming from Ring devices to partner applications.

Overview

• Video only: Live streams deliver video content only — audio is not available
• WebRTC-based: Industry standard for real-time communication
• WHEP protocol: Simplified WebRTC session establishment via HTTP
• Receive only: Partners receive video from the device (recvonly) — no bidirectional media
• Session duration limits: Battery-powered devices up to 30 seconds; line-powered up to 60 seconds

Starting a Live Video Session

Session Initiation

Create an SDP offer using WebRTC and send it to the WHEP endpoint:

POST https://api.amazonvision.com/v1/devices/{device_id}/media/streaming/whep/sessions
Authorization: Bearer <access_token>
Content-Type: application/sdp

[SDP Protocol Offer — generated by WebRTC peer connection]

Successful Response

HTTP/1.1 201 Created
Content-Type: application/sdp
Location: https://api.amazonvision.com/v1/devices/{device_id}/media/streaming/whep/sessions/{session_id}

[SDP Protocol Answer — contains WebRTC connection details]

Key response elements:

• HTTP 201: Successful session creation
• Location header: Session management URL for closing the stream
• SDP Protocol Answer: Connection details for establishing the WebRTC session

Closing a Session

Properly close streaming sessions to optimize battery life:

DELETE https://api.amazonvision.com/v1/devices/{device_id}/media/streaming/whep/sessions/{session_id}
Authorization: Bearer <access_token>

Session Duration Limits

After the maximum duration, the session is automatically terminated. Partners should monitor duration and implement reconnection logic if extended viewing is needed.

Complete WebRTC Implementation

async function startLiveVideo(deviceId, accessToken, videoElement) {
  const whepEndpoint =
    `https://api.amazonvision.com/v1/devices/${deviceId}/media/streaming/whep/sessions`;

  const peerConnection = new RTCPeerConnection({
    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
  });

  // Set up event handlers BEFORE createOffer
  peerConnection.ontrack = (event) => {
    if (event.streams && event.streams[0]) {
      videoElement.srcObject = event.streams[0];
    } else {
      videoElement.srcObject = new MediaStream([event.track]);
    }
    videoElement.play().catch((err) =>
      console.warn('Autoplay blocked:', err)
    );
  };

  peerConnection.onconnectionstatechange = () => {
    if (peerConnection.connectionState === 'failed') {
      console.error('WebRTC connection failed');
    }
  };

  // Video-only receive transceiver (no audio)
  peerConnection.addTransceiver('video', { direction: 'recvonly' });

  // Create and send SDP offer
  const offer = await peerConnection.createOffer();
  await peerConnection.setLocalDescription(offer);

  // Wait for ICE gathering to complete
  await new Promise((resolve) => {
    if (peerConnection.iceGatheringState === 'complete') {
      resolve();
    } else {
      peerConnection.addEventListener('icegatheringstatechange', () => {
        if (peerConnection.iceGatheringState === 'complete') resolve();
      });
    }
  });

  // Send to Ring WHEP endpoint
  const response = await fetch(whepEndpoint, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/sdp'
    },
    body: peerConnection.localDescription.sdp
  });

  if (response.status !== 201) {
    peerConnection.close();
    throw new Error(`WHEP session failed (${response.status})`);
  }

  // Set remote SDP answer
  await peerConnection.setRemoteDescription({
    type: 'answer',
    sdp: await response.text()
  });

  const sessionUrl = response.headers.get('Location');
  return { sessionUrl, peerConnection };
}

async function closeLiveVideo(sessionUrl, peerConnection, accessToken, videoElement) {
  if (videoElement) videoElement.srcObject = null;
  if (peerConnection) peerConnection.close();
  if (sessionUrl) {
    await fetch(sessionUrl, {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${accessToken}` }
    });
  }
}

Error Handling

Common Error Responses

Device Offline (503)

{
  "errors": [{ "status": "503", "title": "Device Unavailable", "detail": "Device is currently offline" }]
}

Invalid Authentication (401)

{
  "errors": [{ "status": "401", "title": "Invalid Client" }]
}

Device Not Found (404)

{
  "errors": [{ "status": "404", "title": "Not Found" }]
}

Common Mistakes

"Incompatible send direction" SDP error

Cause: An audio transceiver was added. Live streams are video only.

Fix: Only add a video transceiver:

// CORRECT:
peerConnection.addTransceiver('video', { direction: 'recvonly' });

// WRONG — do NOT add audio:
// peerConnection.addTransceiver('audio', { direction: 'recvonly' });

No video appearing despite "connected" state

Cause: ontrack handler was attached after setRemoteDescription().

Fix: Always set up ontrack before calling createOffer() or setRemoteDescription().

Texture size [0x0] errors when processing video frames

Cause: Frame processing started before the video element had valid dimensions.

Fix:

function waitForVideoReady(videoElement) {
  return new Promise((resolve) => {
    const check = () => {
      if (videoElement.videoWidth > 0 && videoElement.videoHeight > 0) {
        resolve();
      } else {
        requestAnimationFrame(check);
      }
    };
    check();
  });
}

Best Practices

1. Always close sessions: Use DELETE endpoint when streaming ends
2. Set up event handlers first: Attach handlers before createOffer()
3. Wait for ICE gathering: Only send SDP offer when iceGatheringState === 'complete'
4. Minimize session duration: Close streams when not actively viewing
5. Monitor connection state: Watch connectionState to detect failures
6. Handle reconnection: Implement reconnection logic for extended viewing

Media Clips

Ring provides an endpoint to download historical video content as MP4 files. This complements live video streaming by enabling access to recorded footage for analysis, storage, or playback.

Overview

• MP4 format: Standard video format for broad compatibility
• Configurable quality: Adjustable resolution, frame rate, and codec
• Audio support: Optional audio inclusion
• Flexible duration: Up to 15 minutes per request
• Partial content support: Handles cases where full requested duration isn't available

API Endpoint

Unlike other Ring APIs, the media download endpoint does not follow JSON:API specification and uses standard HTTP constructs with MIME types.

POST https://api.amazonvision.com/v1/devices/{device_id}/media/video/download
Authorization: Bearer <access_token>
Content-Type: application/json

Request Parameters

Required Parameters

Optional Parameters

Video Options

Audio Options

Request Example

{
  "timestamp": 1699457230000,
  "duration": 5000,
  "video_options": {
    "codec": "avc",
    "frame_rate": 5,
    "resolution": {
      "width": 1080,
      "height": 720
    }
  },
  "audio_options": {
    "audio_enabled": true
  }
}

Response Handling

Response Headers

• Content-Type: MIME type for the media content
• X-Media-Timestamp: Actual start timestamp of the provided video
• X-Media-Length: Actual duration in milliseconds (for partial responses)