Account Linking

Account linking is the process by which Ring users connect their Ring account with a partner service. This process ensures user consent and establishes the authentication foundation for the integration.

Process Overview (Legacy Bidirectional Model)

Ring initiates account linking as part of the user journey to configure a partner integration. Users are redirected to a partner login portal where they authenticate and authorize the connection.

Partner Requirements

1. Login Portal with Ring Parameters

Partners must provide a login portal that accepts Ring parameters during redirect:

• redirect_uri: Allowlisted redirect URI back to Ring
• state: One-time use, time-bound state token for security

Example redirect:

https://partner.example.com/login?redirect_uri=https://ring.com/account/integrations/callback&state=abc123xyz

2. Authentication Material Exchange

After user authentication, partners must initiate the OAuth 2.0 authorization code flow:

Redirect format:

<redirect_uri>?state=<state>&code=<authorization_code>

3. Account Information API

Partners must provide an API endpoint that Ring can use to fetch user account information for confirmation:

GET https://api.partner.example.com/v1/integrations/ring
Authorization: Bearer <partner_token>

Response:
{
  "account_identifier": "xxx******xxx@example.com"
}

Requirements:

• Returns obfuscated account identifier (e.g., partial email)
• Enables user confirmation of linked account

4. Ring Credential Transfer API

Partners must be able to receive Ring's authorization code and exchange it for tokens:

POST https://oauth.ring.com/oauth/token

Request:
{
  "grant_type": "authorization_code",
  "code_verifier": "xxxxx",
  "client_id": "<partner_client_id>",
  "code": "<authorization_code>",
  "client_secret": "<secret>"
}

Response:
{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Important:

• Exchange must occur within 1 minute of receiving the code
• Client IDs and secrets are provided during onboarding
• PKCE (Proof Key for Code Exchange) is required for security

Account Linking (One-Way) — Recommended

For new integrations, Ring recommends the one-way account linking model. In this model, Ring releases OAuth credentials upfront and uses an HMAC nonce to cryptographically bind the redirect to a specific Ring user. Partners do not need to operate as OAuth servers.

How the Nonce Flow Works

1. Ring generates a nonce — HMAC-SHA256(K_hmac, "<timestamp_ms>:<account_id>"), encoded as URL-safe Base64 without padding
2. Ring redirects the user to the Partner Account Link URL with query parameters:

   https://partner.example.com/ring/link?nonce=yT8jdW_nu2W4gR6FI-l8hkPpt_c9EAf4DJ9CTIcuM7c&time=1771130906289
   

3. Partner validates timestamp freshness — rejects if older than 600 seconds (10 minutes)
4. User signs in to the partner service (mandatory) — the partner authenticates the user and obtains their partner-side identity
5. Partner matches the nonce — iterates unclaimed tokens, recomputes the HMAC for each using the stored Account ID and the received time, and performs a constant-time comparison
6. Partner claims the matched token and calls POST /v1/accounts/me/app-integrations with the nonce and the account_identifier derived from the signed-in user
7. Partner calls PATCH /v1/accounts/me/app-integrations with status: completed to finalize the integration — this step is mandatory

See App Integrations API for the verification endpoint details and Users API for Account ID retrieval.

Security Properties

Security Considerations

• State tokens prevent CSRF attacks (legacy bidirectional flow)
• Authorization codes are single-use and time-limited
• PKCE adds additional security layer (legacy bidirectional flow)
• HMAC nonces cryptographically bind linking attempts to specific users (one-way flow)
• Partner sign-in is mandatory during account linking
• All redirects must use allowlisted URIs