App Integrations API

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

Overview

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

Both endpoints:

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

Authentication

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

Authorization: Bearer <ava_token>

See Access Tokens for details.

POST — Confirm Account Link

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

When to Call

Call this endpoint after:

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

Request

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

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

Request Fields

Response (200 OK)

{
  "status": "awaiting"
}

Error Responses

Side Effects

When this endpoint is called successfully:

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

Implementation Example

import requests

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

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

PATCH — Update Integration Status

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

When to Call

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

Request

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

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

Request Fields

At least one field must be provided.

Response (200 OK)

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

Error Responses

Integration Status Lifecycle

Required integration flow:

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

Complete Integration Example

import requests

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

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

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

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

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

    return patch_response.json()

Best Practices

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

Next: Live Video Streaming →