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.

Note: Recommended: One-Way Account Linking — Ring AppStore is transitioning to a one-way account linking model where Ring releases OAuth credentials upfront, eliminating the need for partners to operate as OAuth servers. In this model, Ring uses an HMAC-based nonce to cryptographically bind each account linking redirect to a specific Ring user — partners match this nonce to claim the correct token. See Account Linking for the recommended flow. The legacy bidirectional account linking flow documented below remains supported for existing integrations.

Overview

The authentication flow involves:

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

Key Components

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

Authentication Flow

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

Token Types

Access Tokens

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

Refresh Tokens

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

Warning: Common Mistake: Refresh tokens cannot be used as Bearer tokens. If you place a refresh token in the Authorization: Bearer header, API calls will fail with 401 Unauthorized. You must first exchange the refresh token for an access token via POST https://oauth.ring.com/oauth/token. See Refresh Tokens for the exchange flow.

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:

Obtain your client_id and client_secret — These are issued during partner onboarding.
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.
Use the access token in API requests — Include in the Authorization: Bearer <access_token> header.

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

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

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

Security Requirements

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

Sub-pages

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

Next: Device Discovery →