• Release Notes
• App Store Process
  • Getting Started
  • Configure
  • Develop
  • Certify
  • Publish
  • Reports
  • Ring MCP
• UX Design Guide
• Computer Vision Guidelines
• Marketing Guidelines
• Ring API
  • Overview
  • Key Features
  • API Standards
  • Getting Started Steps
  • Quick Links
  • API Reference
  • API Reference Details
    • Base URL
    • Authentication (Bearer token)
    • Rate Limiting
    • Content Types
    • Required HTTP Headers
    • Authentication Endpoints
    • Endpoint Reference
    • Webhook Events
    • Error Responses
    • Testing Your Integration
    • SDKs and Libraries
  • Application Deployment
  • Deployment Steps
    • Prerequisites and Setup
    • App Deployment Journey
    • Service Architecture Overview
    • Endpoint Configuration
    • Token Exchange Flow
    • Account Linking
    • App Integration UX Flow
    • Accessing Devices
    • Webhook Event Delivery
    • Environment Configuration
  • Authentication
  • Account Linking Methods
    • One-Way (Ring-Driven)
    • Partner-Initiated OAuth 2.0
  • Refresh Tokens
  • Access Tokens
  • Users API
  • App Integration
  • Device Discovery
  • Device Details
    • Capabilities
    • Status
    • Locations
    • Configurations
    • Multi-Camera Devices
  • Notifications
    • Notifications
    • Overview
    • Webhook Endpoint Requirements
    • Webhook Authentication & Verification
    • Webhook v1.1 Payload Structure
    • Event Types
    • Webhook Response Handling
    • Retry Logic
    • Common Mistakes
    • Motion Detection
    • Button Press
    • Device Addition
    • Device Removal
    • Device Online
    • Device Offline
    • App Integration Added
    • App Integration Removed
    • Subscription Activated
    • Subscription Deactivated
  • Sensors
    • Sensors
    • Contact Sensors
    • Flood/Freeze Sensor
    • Indoor Temperature/Humidity Sensor
    • Indoor Air Quality Monitor
  • Chimes
    • Chimes
    • Requesting Chime Access
    • Chime Device Discovery
    • Chime Capabilities
    • Chime Configurations
    • Chime Status
    • Playing Audio on a Chime
    • Chime Events
  • Event History
    • Event History
  • Live Video, Media Clips and Image Snapshots
    • Live Video
    • WHEP Live Video Streaming
    • RTSP Live Video Streaming
    • Media Clips
    • Image Snapshots
  • Subscriptions Query API
  • Ring API Use Cases
  • Error Handling
  • Related topics
• Customer Lifecycle Analytics
• Developer FAQ
• Legal Content
  • Ring Appstore Schedule
  • Program Requirements
  • Content Policy
• Ring App Challenge Onboarding Kit

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
• Address individual cameras on multi-camera devices such as Ring Elite

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
• 🎥 Multi-Camera Devices
• 👤 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

Required HTTP Headers

All requests to Ring API endpoints (api.amazonvision.com and oauth.ring.com) must include the following headers in addition to the standard Authorization and Content-Type headers:

Requests that are missing required headers may receive a 406 Not Acceptable response. This status code indicates that Ring's web application firewall has blocked the request.

Example request with required headers:

curl -X GET 'https://api.amazonvision.com/v1/devices' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: HomeGuardian/1.0' \
  -H 'Hardware_Id: 550e8400-e29b-41d4-a716-446655440000'

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.

On a multi-camera device such as Ring Elite, several endpoints accept an optional component_id query parameter to target one camera module. See Multi-Camera Devices.

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
• 406: Not Acceptable — Request blocked by web application firewall
• 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.

There's no way to regenerate credentials on an existing app. If you lose them, or you need to replace them after an exposure, delete the app and create a new one, which issues a fresh set of all three. Use this approach only before you submit the app for certification; after submission, contact Ring support. See Replacing Your App Credentials.

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, exchange them within 60 seconds, then return HTTP 200 (Section 5.3)
• 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 (Nonce Validation and Account Linking)
• 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

When the user completes device selection, Ring Backend generates an OAuth authorization code and sends it directly to your Token Exchange URL (backend-to-backend).

5.2 Token Exchange Sequence

5.3 Handling the Authorization Code Request

Ring sends the authorization code to your Token Exchange URL as a form-encoded POST. Parse the body as form data, not JSON: with JSON parsing, code comes back empty and the link fails without an obvious error.

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

code=<authorization_code>&client_id=<your_client_id>

Read the fields by name rather than assuming a fixed set.

Unlike webhooks, this request isn't one you can verify by signature. Its security comes from the code itself: it works once, expires in 60 seconds, and is useless without your client secret. The HMAC nonce in the account linking step then binds the tokens to one Ring user.

Handle the request in this order, and return 200 only at the end:

1. Exchange the code at POST https://oauth.ring.com/oauth/token (see Exchange Authorization Code).
2. Call GET https://api.amazonvision.com/v1/users/me with the new access token to get the Ring Account ID (see Users API).
3. Store the tokens and the Account ID as unclaimed.
4. Return HTTP 200.

If any step fails, return a non-2xx status. Ring treats a non-2xx response as a failed link and doesn't retry the delivery, so build the handler to succeed on the first call, keep it fast, and make it idempotent.

Ring issues a new authorization code every time a user links, including when they link again. You can therefore receive tokens for a Ring Account ID you already hold. Keep the newest pair, and attach it to the partner account that signs in during account linking, which may not be the one linked before.

5.4 Token Lifecycle

5.5 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

At this point in the deployment journey the Ring user links their Ring account to your partner account. Ring releases OAuth credentials to your backend upfront, redirects the user to your Account Link URL with an HMAC-signed nonce, and your backend matches that nonce to the correct unclaimed token before calling the App-Integrations API to activate the integration.

The full specification for this step — the design rationale, the sequence diagram, the nonce technical reference, and the seven implementation steps — is in One-Way Account Linking, alongside the partner-initiated alternative.

7. App Integration Flow

This section shows the end-to-end app integration experience from two perspectives: a step-by-step walkthrough of the complete account linking flow, and a condensed UX flow diagram that maps the same journey across system components.

7.1 Complete Account Linking Flow

The following flow shows each step a Ring user and your backend go through during account linking, from app discovery to a confirmed integration.

[UI] Step 1 Ring user selects app to enable User browses available apps and selects the app they want to enable

→

[UI] Step 2 Ring user sees app details User views the details and information about the selected app

→

[UI] Step 3 Ring user consents to data access User reviews and provides consent for the app to access their Ring data

→

[UI] Step 4 Ring user selects device to subscribe User chooses which Ring device(s) they want to connect with the app

→

[S2S] Step 5 Token Exchange Sequence starts Partner Backend exchanges the code, then returns 200

→

[S2S] Step 6 Redirects to Partner Account Link URL Backend redirect to partner linking endpoint

→

[UI] Step 7 User clicks Sign in — redirected to app login User is prompted to sign in and redirected to the partner app's login page

→

[UI] Step 8 User creates account or logs in User creates a new account or logs into existing account

→

[S2S] Step 9 Partner Backend verifies user & POSTs the nonce POST app-integrations — Ring verifies the nonce and activates device access

→

[S2S] Step 10 app_integration_added and device_added webhooks sent One device_added per shared device, within seconds of the POST, while the integration is still awaiting

→

[S2S] Step 11 Partner Backend completes linking PATCH app-integrations with status completed

→

[UI] Step 12 User sees "Account Linked Successfully" User receives confirmation that account has been successfully linked

→

[UI] Step 13 User sees Active on Integrations Dashboard User can view the active integration status in their Ring dashboard

7.2 App Integration UX Flow

The following diagram shows the same integration journey as a sequence across the Ring AppStore, Ring API, Partner App UI, and Partner App Backend.

8. Accessing Devices

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

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

8.1 Device Access Sequence

8.2 Authentication Header

All Ring 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.

Account Linking Methods

The following table shows the key similarities and differences between the two account linking methods.

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

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

• One-Way Account Linking — OAuth account linking flow (one-way recommended)
• Partner-Initiated OAuth 2.0 — Partner-initiated account linking with PKCE (invitation only)
• Refresh Tokens — Token refresh and management
• Access Tokens — Using access tokens in API requests

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.

For the partner-initiated alternative, see Partner-Initiated OAuth 2.0 Account Linking. For a side-by-side comparison of both methods, see Account Linking Methods in the Authentication section.

See also: App Integrations API

Why One-Way Account Linking Is Designed the Way It Is

The one-way account linking flow solves a specific problem: how do you securely associate a Ring user's OAuth tokens with the correct partner user, when the tokens arrive on the backend before the partner even knows who the user is?

The Core Challenge

Ring wants to release OAuth credentials upfront — before the user logs into the partner service. This means the partner receives tokens for a Ring user but has no idea which partner user they belong to. The tokens are "unclaimed."

Why Not Just Send the Ring Account ID in the Redirect?

Because the redirect goes through the user's browser. Anything in the URL can be intercepted, modified, or forged. An attacker could swap the Account ID and trick the partner into linking the wrong Ring account to their partner account. There's no way to verify the value is legitimate.

Why the HMAC Nonce?

The nonce is a cryptographic proof that the redirect came from Ring and corresponds to a specific Ring user. It's computed as HMAC-SHA256(K_hmac, "<time>:<account_id>") using a shared secret that only Ring and the partner know: the HMAC Key. An attacker can't forge it without the HMAC key. The partner can verify it by recomputing the HMAC against each unclaimed token's Account ID and prefixing it with the time provided in the redirect — only the correct one will match.

Why Does the Partner Need to Call /v1/users/me Separately?

To get the Account ID through a trusted backend channel (the access token), not from the browser. This keeps the Account ID out of the URL entirely. The partner stores it server-side, and later uses it to verify the nonce — also server-side.

Why Is a Verified Partner Identity Required?

The requirement is not that the customer signs in. It is that the identity you attach to the claimed token comes from a source Ring can trust: the Ring email returned by the Users API for the token that matched the nonce. Never attach an identity supplied by the browser. Anyone who intercepts the nonce redirect can send any email address.

There are two ways to meet this requirement:

• Passwordless (recommended). Fetch the customer's Ring email server-side with the nonce-matched token and link automatically. No sign-in, no form. The verified identity still comes from the token, so the requirement is met with zero customer input.
• Partner sign-in. The customer signs in or creates an account, and you derive the identity from that authenticated session. Use this when your service needs its own credentials.

Both are valid. What is mandatory is the identity binding, not the sign-in.

Implementation requirements

Do the linking work on your server. Match the nonce, look up the customer's email with the Users API, and claim the token on your server. The browser should only pass nonce and time along.

Check that the link is fresh everywhere it's used. Any server endpoint that receives nonce and time must reject the request if time is more than 600 seconds old or in the future. This applies to every such endpoint, not only the page Ring first redirects to.

Keep sensitive data out of URLs. URLs are saved in browser history and server logs, and they can leak to other websites. Treat anything in a URL as public.

• Ring email: Don't add it to a redirect URL. Have your server include it in the page it returns, or have the page request it from your backend.
• Signing the customer in after linking: Don't put your app's sign-in tokens in the redirect URL. Set a secure cookie instead, or redirect with a one-time code that expires within a minute and that your app exchanges with your backend.
• Ring access and refresh tokens: Never send them to the browser. Keep them on your server.

Why the Two-Step POST + PATCH?

The POST sends the nonce back to Ring for server-side verification and transitions the integration to awaiting. The PATCH lets the partner signal "I'm fully configured" and moves to completed. This separation allows partners that need additional setup steps after linking to do so before finalizing.

Summary

The design boils down to: Ring releases credentials early (better UX, simpler partner infrastructure), and the HMAC nonce is the mechanism that securely binds those credentials to the right user despite the tokens arriving before the user identifies themselves on the partner side.

Full Account Linking Sequence

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 finishes approving data access and selecting devices in the Ring AppStore, Ring Backend generates a cryptographically signed nonce 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***[email protected]",
  "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. Ring also sends an app_integration_added webhook and one device_added webhook for each shared device. These can arrive before your POST call returns.

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.

Partner-Initiated OAuth 2.0 Account Linking

This section describes Ring AppStore's Partner-Initiated OAuth 2.0 Account Linking — an account linking method that enables partners to start the linking flow from their own platforms. With this method, your app presents a "Connect Ring Account" button; the user is redirected to Ring for login, consent, and device selection; and Ring redirects the user back to your app with a standard OAuth 2.0 authorization code.

This is a standard OAuth 2.0 authorization code flow with PKCE (S256). If you have implemented OAuth 2.0 before, the mechanics are familiar.

For the Ring-driven alternative, see One-Way Account Linking. For a side-by-side comparison of both methods, see Account Linking Methods in the Authentication section.

Availability: Partner-Initiated OAuth 2.0 is currently available by invitation only. Contact your Ring AppStore partner representative to request access.

Terminology

This section uses the following terms consistently:

Terminology note: "Ring base plan" is unrelated to whether an app is free or paid. A Ring base plan is what users pay Ring for cloud features on their devices — it determines which devices are eligible for sharing. Whether users pay the partner to use the app is a separate concept (free app vs. paid app). A user needs a Ring base plan on their devices regardless of whether the partner app is free or paid.

Flow Overview

The following diagram illustrates the Partner-Initiated OAuth 2.0 flow. The initiating participant is on the left, so reading left to right follows the flow.

Key characteristics:

• Partner initiates the flow — user never needs to visit Ring AppStore first
• Standard OAuth 2.0 authorization code + PKCE
• No nonce, no unclaimed token pool — the Bearer token proves possession
• Partner confirms the link via PATCH /v1/accounts/me/app-integrations

For the one-way (Ring-driven) flow diagram, see One-Way Account Linking.

Prerequisites

Before implementing Partner-Initiated OAuth 2.0 account linking, confirm that:

1. Your app is created in the Ring Developer Portal. App creation, certification, and publishing follow the same process as any other Ring AppStore app — see Getting Started.
2. Your app is allowlisted for Partner-Initiated OAuth 2.0 (see Requesting access below).
3. You have your partner credentials: client_id, client_secret, and hmac_signing_key — issued during onboarding via the Ring Developer Portal.

Requesting access

Partner-Initiated OAuth 2.0 is gated behind an internal allowlist. To request access and have your app shown as Free, open a support case, select Type of Inquiry: Ring Appstore, and include the following information:

After allowlisting is complete, the Partner-Initiated OAuth 2.0 configuration fields become available on the Account Linking page of your app in the Developer Portal.

Developer Portal Configuration

After your app is allowlisted, configure the account linking settings in the Ring Developer Portal.

Account linking fields

Navigate to your app → Account linking. The page has separate Staging settings and Production settings tabs — configure both. Under Authorization, provide the following:

All four values must use HTTPS.

Webhook URL is required even if you plan to poll. You must register an endpoint that returns 200. If you aren't ready to process webhooks at launch, acknowledge deliveries with 200 and use the Event History API instead — see API polling alternative.

Staging and production settings

Configure each environment on its own tab:

• Staging settings — used while you develop and test your integration
• Production settings — used by live Ring users after your app is certified and published

Save each tab separately. Values do not carry over between environments, so register the redirect URIs for each environment where your app runs.

Redirect URI rules

• All redirect URIs must use HTTPS
• Ring validates using exact match — scheme, domain, path, and port must match precisely
• No wildcard or prefix matching

What stays the same

Everything outside of account linking configuration is unchanged:

• App creation and metadata (name, description, icon, supported devices)
• Certification and review process
• Publishing to Ring AppStore
• Scopes — declared and approved during app submission, not configured separately

Implementation Guide

This section walks through the complete implementation of Partner-Initiated OAuth 2.0 account linking.

Step 1: Generate PKCE parameters

Before redirecting the user, generate a PKCE code verifier and code challenge.

import secrets
import hashlib
import base64

def generate_pkce():
    """Generate PKCE code_verifier and code_challenge (S256)."""
    # Generate a random code verifier (43-128 characters)
    code_verifier = secrets.token_urlsafe(32)

    # Compute SHA-256 hash and Base64URL-encode it (no padding)
    digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
    code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")

    return code_verifier, code_challenge

Store code_verifier securely in your session — you need it for the token exchange in Step 4.

Step 2: Redirect user to Ring

This is the work your Account Link URL performs. Users reach that page either by choosing "Connect Ring Account" in your app or by being forwarded from your Ring AppStore listing. Either way, the page redirects the user's browser to Ring's authorization endpoint with the following parameters:

https://account.ring.com/account/integrations/partner-link/authorize
  ?client_id=<your_client_id>
  &redirect_uri=<your_registered_redirect_uri>
  &response_type=code
  &scope=<approved_scope>
  &state=<random_csrf_token>
  &code_challenge=<code_challenge>
  &code_challenge_method=S256

Authorization request parameters

Example redirect

from flask import redirect, session
import secrets

@app.route("/connect-ring")
def connect_ring():
    # Generate PKCE pair
    code_verifier, code_challenge = generate_pkce()

    # Generate CSRF state token
    state = secrets.token_urlsafe(16)

    # Store both in session for later validation
    session["pkce_code_verifier"] = code_verifier
    session["oauth_state"] = state

    # Build the authorization URL
    auth_url = (
        "https://account.ring.com/account/integrations/partner-link/authorize"
        f"?client_id={CLIENT_ID}"
        f"&redirect_uri={REDIRECT_URI}"
        f"&response_type=code"
        f"&scope=ava.v1:read"
        f"&state={state}"
        f"&code_challenge={code_challenge}"
        f"&code_challenge_method=S256"
    )

    return redirect(auth_url)

What happens at Ring

After you redirect the user:

1. Login — If the user is not signed in to Ring, they see the Ring login page (with 2FA if enabled on their account)
2. Permission agreement — The user reviews and approves the data access scopes your app requests
3. Device selection — The user selects which Ring devices to share with your app. Only devices covered by an active Ring base plan are selectable.
4. Redirect back — Ring redirects the user to your redirect_uri with ?code=<authorization_code>&state=<your_state>

Ring base plan requirement: Users can only share devices that have an active Ring base plan. If no devices are covered, the user is informed they need a Ring base plan and the flow cannot proceed. The user must return to your app and re-initiate after purchasing a plan.

Step 3: Handle the callback

When Ring redirects the user back to your redirect_uri, validate the response and extract the authorization code.

Successful callback

https://your-app.example.com/callback?code=<authorization_code>&state=<your_state>

Error callback

If the user cancels or an error occurs, Ring redirects with an OAuth error:

https://your-app.example.com/callback?error=<error_code>&error_description=<description>&state=<your_state>

For the full list of error_description values and how to handle each one, see Error Handling Reference.

Callback handler example

@app.route("/callback")
def oauth_callback():
    # Validate state to prevent CSRF
    received_state = request.args.get("state")
    if received_state != session.get("oauth_state"):
        return "Invalid state parameter", 403

    # Check for errors
    error = request.args.get("error")
    if error:
        error_description = request.args.get("error_description", "")
        return f"Authorization failed: {error} — {error_description}", 400

    # Extract the authorization code
    authorization_code = request.args.get("code")
    if not authorization_code:
        return "Missing authorization code", 400

    # Proceed to token exchange (Step 4)
    tokens = exchange_code_for_tokens(authorization_code)
    return handle_successful_linking(tokens)

Step 4: Exchange authorization code for tokens

Exchange the authorization code at Ring's token endpoint. You must include the code_verifier for PKCE validation.

Request

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

grant_type=authorization_code
code=<authorization_code>
code_verifier=<code_verifier>
client_id=<your_client_id>
client_secret=<your_client_secret>

Response (200 OK)

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "ava.v1:read",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Token exchange example

import time

import requests

def exchange_code_for_tokens(authorization_code):
    """Exchange the authorization code for access and refresh tokens."""
    code_verifier = session.pop("pkce_code_verifier")

    response = requests.post(
        "https://oauth.ring.com/oauth/token",
        data={
            "grant_type": "authorization_code",
            "code": authorization_code,
            "code_verifier": code_verifier,
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
        },
        headers={"Content-Type": "application/x-www-form-urlencoded"},
    )

    if response.status_code != 200:
        raise Exception(f"Token exchange failed: {response.text}")

    tokens = response.json()

    # Store tokens securely — associated with the authenticated partner user
    store_user_tokens(
        partner_user_id=get_current_user_id(),
        access_token=tokens["access_token"],
        refresh_token=tokens["refresh_token"],
        expires_at=time.time() + tokens["expires_in"],
    )

    return tokens

Important: The authorization code is single-use and expires within 10 minutes. Exchange it immediately after receiving it. Note that this differs from one-way account linking, where the authorization code expires after 60 seconds.

Step 5: Confirm the account link

After obtaining tokens, call the App Integrations API to finalize the account link. This step transitions the integration to a fully active state.

Request

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

{
  "status": "completed",
  "account_identifier": "u***[email protected]"
}

Response (200 OK)

{
  "account_identifier": "u***[email protected]",
  "status": "completed",
  "updated_at": "2026-07-28T14:30:00Z"
}

Confirmation example

import requests

def confirm_account_link(access_token, partner_email):
    """Confirm the account link with Ring — finalizes the integration."""
    response = requests.patch(
        "https://api.amazonvision.com/v1/accounts/me/app-integrations",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        },
        json={
            "status": "completed",
            "account_identifier": mask_email(partner_email),
        },
    )

    if response.status_code != 200:
        raise Exception(f"Account link confirmation failed: {response.text}")

    return response.json()


def mask_email(email):
    """Mask email for privacy: u***[email protected]"""
    local, domain = email.split("@")
    if len(local) <= 2:
        masked = local[0] + "***"
    else:
        masked = local[0] + "***" + local[-1]
    return f"{masked}@{domain}"

Important: The integration is not fully active until you call this endpoint with status: "completed". Without this call, device consents remain inactive and you cannot receive webhook notifications.

Note: Unlike one-way account linking, no POST call with a nonce is required — Partner-Initiated OAuth 2.0 uses only the PATCH call. See App Integration for the full endpoint reference.

Step 6: Start using the Ring API

After confirmation, you can call Ring APIs using the access token:

import requests

def get_devices(access_token):
    """List all Ring devices shared with your app."""
    response = requests.get(
        "https://api.amazonvision.com/v1/devices?include=status,capabilities",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        },
    )
    return response.json()

For the full API reference, see API Reference.

Token Management

Token lifetimes and the refresh flow are identical to one-way account linking, with one exception — the authorization code lifetime:

Refresh tokens proactively — each refresh returns a new refresh_token that invalidates the old one, and an expired refresh token requires the user to re-link from scratch. For the complete refresh flow and best practices, see Refresh Tokens and Access Tokens.

Webhook Notifications

After account linking is complete, Ring delivers real-time event notifications to your Webhook URL. Webhook delivery, HMAC-SHA256 signature verification, payload structure, and retry logic are identical to one-way account linking — no difference in how you verify or handle them. See Notifications for full webhook documentation, including signature verification.

API polling alternative

If your architecture cannot support inbound webhooks at initial launch, you can use Ring's Event History API to poll for events:

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

Webhook support via HMAC signing is available whenever you are ready to enable it.

App Discovery from Ring AppStore

Although Partner-Initiated OAuth 2.0 flows normally start from your app, your app is still listed on Ring AppStore. When a user discovers your app there and starts linking from your listing:

• Ring forwards the user to your Account Link URL (configured in the Developer Portal)
• Your page then starts the flow the same way it would for a user who began on your platform — redirect to Ring's authorization endpoint with the OAuth and PKCE parameters
• This differs from one-way account linking, where the Ring AppStore runs the consent and device-selection screens itself before sending the user to your Account Link URL

This ensures a single, consistent account linking path regardless of where the user discovers your app.

Managing and Removing Integrations

Post-linking management

Device selection changes and permission review are handled by the Ring user within Ring AppStore. Partners have no API to change a user's device access or permissions. Partners can change two things about the integration itself: pause and resume it — see Pausing the integration — and remove it — see Removing the integration.

Partner-side UX requirement

When a user wants to change their device selection or review permissions from within your app, you must navigate them to the Ring AppStore page for your app. There is no API for changing a user's device selection, so don't attempt it from your own UI. To let the user disconnect Ring from within your app, call DELETE /v1/accounts/me/app-integrations — see Removing the integration.

Example implementation:

# When user clicks "Manage Ring Connection" in your app
RING_APPSTORE_MY_APPS_URL = "https://account.ring.com/account/integrations"

def get_manage_ring_url():
    """Return the URL where users manage their Ring integration."""
    return RING_APPSTORE_MY_APPS_URL

Pausing the integration

You can pause an active integration instead of removing it. Call the same PATCH /v1/accounts/me/app-integrations endpoint you used to activate the link, with status set to awaiting instead of completed. This moves the integration back to the awaiting state, which is useful when your service is undergoing maintenance, when you need to suspend event processing temporarily, or when your own configuration for that user is incomplete.

Pausing is reversible. Call the endpoint again with status set to completed to resume. Pausing does not invalidate tokens and does not remove the account link — the user's device authorizations and your stored credentials remain intact.

Request

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

{
  "status": "awaiting"
}

Example implementation

import requests

AVA_BASE_URL = "https://api.amazonvision.com"


def set_integration_status(access_token, status):
    """Pause or resume a Ring integration.

    Pass status="awaiting" to pause, status="completed" to resume.
    """
    if status not in ("awaiting", "completed"):
        raise ValueError("status must be 'awaiting' or 'completed'")

    response = requests.patch(
        f"{AVA_BASE_URL}/v1/accounts/me/app-integrations",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        },
        json={"status": status},
    )

    if response.status_code != 200:
        raise Exception(f"Status update failed: {response.text}")

    return response.json()


def pause_integration(access_token):
    """Pause the integration — for example, during maintenance."""
    return set_integration_status(access_token, "awaiting")


def resume_integration(access_token):
    """Resume a paused integration."""
    return set_integration_status(access_token, "completed")

Use a valid access token. Pausing requires the access token for the specific Ring user whose integration you are pausing. Refresh the token first if it has expired.

Removing the integration

To unlink a Ring user from your app, call DELETE on the same /v1/accounts/me/app-integrations endpoint. Ring removes the integration for the Ring user identified by the Bearer token and revokes that user's access and refresh tokens. Use it when the user disconnects Ring from within your app or closes their account with you.

Removal is permanent. The user must go through the account linking flow again to reconnect. If you only need to stop event processing for a while, pause the integration instead.

Unlike POST and PATCH on this endpoint, DELETE takes no request body and no Content-Type header — the target integration comes from the Bearer token.

Availability: DELETE /v1/accounts/me/app-integrations works only for apps that use Partner-Initiated OAuth 2.0. Apps that use one-way (Ring-driven) account linking receive 403 Forbidden; their users remove the integration from Ring AppStore.

Request

DELETE https://api.amazonvision.com/v1/accounts/me/app-integrations
Authorization: Bearer <access_token>

Response (200 OK)

{
  "data": {
    "type": "app-integrations",
    "id": "ava1.ring.client.<client_id>",
    "attributes": {
      "status": "deleted"
    }
  },
  "meta": {
    "time": "2026-09-15T14:30:00Z"
  }
}

After a successful call, Ring does exactly what it does when a user removes your app from Ring AppStore: it invalidates the user's access and refresh tokens, stops sending webhook events for that user, and sends an app_integration_removed webhook — see Handling removal notifications. Discard the stored tokens as soon as the call returns 200 OK; do not wait for the webhook.

Example implementation

import requests

AVA_BASE_URL = "https://api.amazonvision.com"


def remove_integration(access_token):
    """Unlink the Ring user and revoke their tokens.

    Call this when the user disconnects Ring from your app. The access
    token must belong to the Ring user being unlinked.
    """
    response = requests.delete(
        f"{AVA_BASE_URL}/v1/accounts/me/app-integrations",
        headers={"Authorization": f"Bearer {access_token}"},
    )

    if response.status_code == 404:
        # Already removed — for example, by the user from Ring AppStore
        return None

    if response.status_code != 200:
        raise Exception(f"Integration removal failed: {response.text}")

    return response.json()["data"]["attributes"]

Use a valid access token. Removal requires the access token for the specific Ring user whose integration you are removing. Refresh the token first if it has expired.

Handling removal notifications

When a user removes your app from Ring AppStore, or your app removes the integration with DELETE, Ring:

1. Immediately invalidates the associated access and refresh tokens
2. Stops sending webhook events
3. Sends an app_integration_removed webhook (if your endpoint is reachable)

Your app should handle 401 Unauthorized responses gracefully as an indicator that the user has removed the integration. Prompt the user to re-link if they want to reconnect.

Security Requirements for Partner-Initiated OAuth 2.0

PKCE (S256) — mandatory

PKCE prevents authorization code interception attacks. It is mandatory for all Partner-Initiated OAuth 2.0 flows. Ring rejects authorization requests that do not include code_challenge and code_challenge_method=S256.

Redirect URI validation

• Ring performs exact-match validation (scheme + domain + path + port)
• No prefix matching, wildcard matching, or partial matching
• If the redirect_uri in the authorization request does not match a registered URI, Ring shows an error page — it does not redirect to the unvalidated URI

State parameter

• You must include a non-empty, unpredictable state parameter in every authorization request
• Ring echoes it back exactly in the redirect
• Validate that the returned state matches what you stored in the user's session
• This prevents CSRF attacks

Token storage

• Ring does not store your (partner) user credentials
• You are responsible for securely storing Ring access and refresh tokens
• If tokens are lost, the user must re-link from scratch
• Associate tokens with the specific partner user who completed the linking

Differences from One-Way Account Linking

If you are already integrated with one-way (Ring-driven) account linking, the following table shows what changes with Partner-Initiated OAuth 2.0.

Implementation Checklist

Use this checklist to verify your integration is complete.

Developer Portal

• App created in Ring Developer Portal
• App allowlisted for Partner-Initiated OAuth 2.0 (Vendor ID + App ID provided to Ring)
• OAuth Redirect URI(s) registered (HTTPS, exact-match)
• Account Link URL configured
• App Homepage URL configured
• Webhook URL configured
• Staging settings and Production settings both saved
• App submitted for certification

Code — Account Linking

• PKCE generation (code_verifier + code_challenge with S256)
• Authorization redirect to account.ring.com/account/integrations/partner-link/authorize
• state parameter generated, stored in session, and validated on callback
• Callback handler validates state and checks for error responses
• Token exchange at oauth.ring.com/oauth/token with code_verifier
• Account link confirmation via PATCH /v1/accounts/me/app-integrations with status: "completed"
• Tokens stored securely, associated with the partner user

Code — Token Management

• Proactive token refresh before expiry (background job recommended)
• New refresh token stored on every refresh
• 401 Unauthorized handling — refresh and retry, or prompt re-link if refresh fails
• Graceful handling when user removes the integration (all tokens invalidated)

Code — Webhooks

• Webhook endpoint accepts POST with application/json
• HMAC-SHA256 signature verification using raw body bytes
• Idempotency handling via meta.request_id
• Response within five seconds (async processing recommended)

User Experience

• "Connect Ring Account" button in your app initiates the flow
• "Manage Ring Connection" navigates the user to Ring AppStore
• Optional — "Disconnect Ring Account" calls DELETE /v1/accounts/me/app-integrations and discards the stored tokens
• Error states handled (user cancels, Ring base plan required, server errors)
• Re-link prompt shown when tokens are invalidated

Error Handling Reference

Authorization errors (redirect to partner)

These errors are returned as query parameters on your redirect_uri:

Authorization errors (shown on Ring error page — no redirect)

Token exchange errors

App Integrations API errors

Frequently Asked Questions

Can my app support both one-way and partner-initiated account linking?

Partners can support only one account linking method per app. An app configured for Partner-Initiated OAuth 2.0 uses that method exclusively. If a user discovers the app on Ring AppStore and starts linking there, Ring forwards them to your Account Link URL, which starts the partner-initiated flow.

Do I need a Token Exchange URL?

No. The Token Exchange URL is specific to one-way (Ring-driven) account linking, where Ring POSTs the authorization code to your backend. In Partner-Initiated OAuth 2.0 you receive the authorization code on your registered OAuth Redirect URI via browser redirect, then exchange it yourself at https://oauth.ring.com/oauth/token.

Do I need to implement HMAC nonce matching?

No. The nonce mechanism is specific to one-way account linking. In Partner-Initiated OAuth 2.0, the Bearer token obtained through the code exchange is the proof of possession.

What happens if the user has no Ring base plan?

Users can only share devices covered by an active Ring base plan. If no devices qualify, Ring shows a message explaining the requirement. The flow terminates and the user must return to your app after purchasing a plan to re-initiate.

What if the user is already linked to my app?

One active link per user per app. Ring blocks duplicate linking attempts. The user must remove their existing integration from Ring AppStore before re-linking.

Can I programmatically unlink a user?

Yes. Call DELETE /v1/accounts/me/app-integrations with the user's access token. Ring removes the integration, revokes the user's tokens, and sends an app_integration_removed webhook — see Removing the integration. This works for Partner-Initiated OAuth 2.0 apps only. If you only need to stop event processing temporarily, pause the integration instead.

How do I pause an integration without unlinking the user?

Call PATCH /v1/accounts/me/app-integrations with status set to awaiting. Resume by calling it again with status set to completed. Pausing keeps tokens and device authorizations intact — see Pausing the integration.

What are the token lifetimes?

Access token: ~4 hours. Refresh token: ~30 days. You must refresh tokens proactively — an expired refresh token requires the user to re-link.

Do webhooks work the same way?

Yes. Webhook delivery, HMAC-SHA256 signature verification, payload structure, and retry logic are identical regardless of which account linking method was used. See Notifications.

Related Documentation

• API Reference — Full endpoint reference
• Authentication — OAuth overview and token types
• Access Tokens — Token usage and management
• Refresh Tokens — Token refresh flow
• Notifications — Webhook events and HMAC verification
• App Integration — App Integrations API reference
• Device Discovery — Listing and querying devices
• One-Way Account Linking — The Ring-driven account linking method
• Getting Started — App creation and onboarding

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
• Each refresh returns a new refresh_token and invalidates the old one. Store the new token every time you refresh
• 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
• One-Way 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
• One-Way 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": "[email protected]"
    }
  }
}

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 One-Way 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)
• Accept standard JSON request bodies (Content-Type: application/json)
• Return JSON:API formatted responses — the resource is wrapped in a data object alongside a meta object

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***[email protected]",
  "nonce": "<nonce_value>"
}

Request Fields

Response (200 OK)

{
  "data": {
    "type": "app-integrations",
    "id": "ava1.ring.client.<client_id>",
    "attributes": {
      "status": "awaiting"
    }
  },
  "meta": {
    "time": "2026-07-21T07:07:15Z"
  }
}

Response Fields

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
• Ring sends an app_integration_added webhook and one device_added webhook for each shared device, typically within seconds. They can arrive before this call returns.

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:
        # Status is nested inside the JSON:API envelope
        return response.json()["data"]["attributes"]["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***[email protected]",
  "status": "completed"
}

Request Fields

At least one field must be provided.

Response (200 OK)

{
  "data": {
    "type": "app-integrations",
    "id": "ava1.ring.client.<client_id>",
    "attributes": {
      "account_identifier": "u***[email protected]",
      "status": "completed",
      "updated_at": "2026-07-21T07:07:16Z"
    }
  },
  "meta": {
    "time": "2026-07-21T07:07:16Z"
  }
}

Response Fields

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()}")

    # Attributes are nested inside the JSON:API envelope
    return patch_response.json()["data"]["attributes"]

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": "ava1.ring.device.location.XXXYYY"
          },
          "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

Devices with multiple cameras

A Ring Elite camera contains several camera modules but returns a single device entry, structurally identical to any other camera. Sideload capabilities with ?include=capabilities and check for a components object in the device-capabilities resource: its presence tells you the device has multiple camera modules and lists them. Devices without components are single-camera devices.

For the full model, see Multi-Camera Devices.

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
• Multi-Camera Devices — Addressing individual cameras on Ring Elite devices

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>
   

3. A single camera module on a multi-camera device, using the component_id query parameter:

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

Response Structure

{
  "meta": {
    "time": "2025-07-07T10:30:00Z"
  },
  "data": {
    "id": "xxxyyy.capabilities",
    "type": "device-capabilities",
    "attributes": {
      "button_press": {
        "supported": true
      },
      "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

Button Press

• supported: true when the device is a doorbell and sends Button Press events

Doorbells return the button_press object. Other devices don't, so treat a missing button_press object as no doorbell button. Read it at discovery time to choose the experience you offer for a device before any event arrives.

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
• component_id: On a multi-camera device, the camera module this block describes

Components

Devices with more than one camera module — the Ring Elite lineup — list them under components. The field is absent on single-camera devices.

The array order matches the physical arrangement of the modules. See Multi-Camera Devices.

Motion Detection Capability

• 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

Per-component capabilities

Request one camera module's metadata with the component_id query parameter.

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

{
  "data": {
    "type": "component-capabilities",
    "id": "ava1.ring.component.capabilities.XXXYYY",
    "attributes": {
      "component_type": "lens",
      "component_id": "5",
      "component_name": "View 6"
    },
    "relationships": {
      "configurations": {
        "links": {
          "related": "/v1/devices/{device_id}/configurations?component_id=5"
        }
      }
    }
  },
  "meta": {
    "time": "2026-08-14T13:42:45Z"
  }
}

The scoped response returns identity metadata only — component_type, component_id, and component_name. Video, motion detection, and image enhancement capabilities aren't scoped per component. Read those from the device-level response, which describes the first component in components.items.

Note the resource type is component-capabilities (not device-capabilities) and the id uses the ava1.ring.component.capabilities. prefix.

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}

def supports_doorbell_press(device_capabilities):
    button_press = device_capabilities.get('attributes', {}).get('button_press', {})
    return button_press.get('supported') is True

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>
   

3. A single camera module on a multi-camera device, using the component_id query parameter:

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

Response Structure

{
  "meta": {
    "time": "2026-02-14T23:37:48Z"
  },
  "data": {
    "type": "device-configurations",
    "id": "ava1.ring.device.configurations.XXXYYY",
    "attributes": {
      "e2e_encryption": {
        "enabled": false
      },
      "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}
            ]
          }
        ],
        "component_id": "0"
      },
      "video": {
        "component_id": "0"
      },
      "image_enhancements": {
        "color_night_vision": "off",
        "hdr": "off",
        "ir_led_night_vision": "off",
        "auto_zoom_track": "off",
        "privacy_zones": []
      }
    }
  }
}

Configuration Categories

End-to-End Encryption

• enabled: Whether video encryption is turned on for this device (true or false). When true, video requests for the device still succeed but return encrypted content your app cannot read

Motion Detection Configuration

• 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
• component_id: On a multi-camera device, the camera module these zones belong to

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)

Per-component configurations

Scope the configurations request to one camera module with the component_id query parameter.

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

{
  "data": {
    "type": "component-configurations",
    "id": "ava1.ring.component.configurations.XXXYYY",
    "attributes": {
      "component_name": "View 6",
      "component_id": "5",
      "component_type": "lens"
    }
  },
  "meta": {
    "time": "2026-08-14T13:42:16Z"
  }
}

The scoped response returns identity metadata only. Motion zones, video settings, and image enhancements aren't yet scoped per component — read them from the device-level configurations response, which describes the first component in components.items and names it in motion_detection.component_id.

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

Video Encryption

def is_video_readable(device_config):
    encryption = device_config.get('attributes', {}).get('e2e_encryption', {})
    return not encryption.get('enabled', False)

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

Multi-Camera Devices

Some Ring cameras contain more than one camera module in a single physical unit. Ring Elite cameras combine several camera modules covering different parts of a panoramic field of view, and report themselves to the API as one device.

Each camera module is a component, addressed by a component_id. Discovery tells you how many components a device has; a component_id query parameter lets you target one of them for capabilities, configurations, and live streaming.

The Ring Elite lineup

Detecting a multi-camera device

A multi-camera device exposes a components object in its device-capabilities resource. Single-camera devices omit components entirely — its absence is how you identify a standard single-camera device.

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

The components.items array lists every camera module in physical order. The following response is from a Ring Elite 360.

{
  "type": "device-capabilities",
  "id": "ava1.ring.device.capabilities.XXXYYY",
  "attributes": {
    "components": {
      "items": [
        { "component_id": "0", "component_type": "lens", "component_name": "View 1" },
        { "component_id": "1", "component_type": "lens", "component_name": "View 2" },
        { "component_id": "2", "component_type": "lens", "component_name": "View 3" },
        { "component_id": "3", "component_type": "lens", "component_name": "View 4" },
        { "component_id": "4", "component_type": "lens", "component_name": "View 5" },
        { "component_id": "5", "component_type": "lens", "component_name": "View 6" }
      ]
    }
  }
}