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

Warning: Only access tokens can be used in Authorization: Bearer headers. Refresh tokens are not valid Bearer tokens — using a refresh token in the Authorization header will result in 401 Unauthorized errors. If you only have a refresh token, you must first exchange it for an access token via POST https://oauth.ring.com/oauth/token. See Refresh Tokens for the exchange flow.

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

Track expiration: Monitor token expiration times
Proactive refresh: Refresh tokens before they expire
Handle 401 responses: Implement automatic token refresh on authentication failures
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

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