Users API

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

Overview

Authentication

Requires a valid AVA access token:

Authorization: Bearer <ava_token>

See Access Tokens for details on obtaining and managing tokens.

GET — User Profile

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

Request

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

No request body is required.

Response (200 OK)

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

Response Fields

Error Responses

Key Uses of Account ID

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

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

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

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

Implementation Example

Basic Profile Retrieval

import requests

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

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

Store Account ID at Token Receipt

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

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

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

    return account_id

Best Practices

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

Next: App Integrations →