Data Portability Overview

Ring Data Portability offers authorized third parties the capability to programmatically import Ring customers' data to an app or website after the customers give authorization through Login With Ring (LWR).

Ring Data Portability allows 3P apps or websites to access and retrieve a customer's Ring data, based on the customer's explicit authorization through Ring Data Portability scopes. The Scopes are defined the type of data the customers are authorizing third parties to access. See RingScopes for details.

This document explains how Ring Data Portability works and guides you through these three-high level sections: (1) configure the Ring Data Portability service, (2) authorize your app and/or website, and (3) connect with Ring Data Portability API. You need to complete the steps in each section before your app or website can import customers' data.

Ring Data Portability enables customers to programmatically port to authorized third party apps or websites portions of their Ring data from these countries: Belgium, France, Germany, Ireland, Italy, Netherlands, Poland, Spain, and Sweden.

This document assumes that you have an app or website ("Application") ready to add the Login With Ring button. This doesn’t cover guidelines on how to build an Application.

Want to know how Ring Data Portability works? Proceed to Ring Data Portability workflow.

Ring Data Portability workflow

From your Application, Ring customers will use the Login with Ring button. Ring will display the Sign in page where customers sign in using their Ring credentials. The Sign in operation is paired with Transaction Intent Verification to verify Ring customer’s credentials. If customers sign in, Ring displays the Authorization page with available Ring Data Scopes.

Sample User Transfer Preferences page

On the Authorization page, customers select Confirm or Cancel. If the customer selects Cancel, the workflow ends. Your Application won’t have the capability to import that customer’s data. If the customer selects Confirm, Ring displays the User Sharing Preferences page.

Ring Data Portability scopes can be requested by your Application, which means that a customer can review and consent the information they will be sharing.

On the User Sharing Preferences page, Ring provides option for the customers to set their preferences, acknowledge the authorization, and select the Cancel or Authorize button. If the customer selects the Authorize button, it activates the Ring Data Portability in your Application, providing authorization to import that customer’s data. If the customer selects Cancel, your Application won't be authorized to import that customer's data.

Once the customer selects Authorize, you will use the Login with Ring to get the customer’s authorization (OAuth2) code. You will use the OAuth code to get access and refresh tokens, which you will need to call the Ring Data Portability API and import the customer’s data in your Application.

🚧 Importing user data in your Application is asynchronous. Please ensure your Application has an HTTPS endpoint.

Want to learn how Ring provides option for the customers to select what data to consent to?Proceed to User Transfer Preferences.

User transfer preferences

Data that are ported to your Application depends on the preferences set by the customer in the User Transfer Preferences page.

User Transfer Preferences page

How much data to transfer?

Customers select how much data your Application can import by selecting a past date. The drop-down list offers these options: 5 days ago, 30 days ago, 60 days ago, 1 year ago and Since date xx/xx/xxxx.

For how long do you authorize the transfer?

Customers select how long your Application can import data by selecting a future date. The drop-down list offers these options: One time transfer, For the next 30 days, For the next 90 days, For the next 180 days, and For the next 1 year. Once the selected period expires, your Application will be unable to import customers data unless the customer provides a new authorization.

🚧 Authorization ends when customers revoke access or tokens expire. Customers receive an email about authorization changes and expirations.

Developer data handling practices

Customers are informed that their data will be handled subject to your privacy practices and policies.

I authorize the third party to receive my EU data
Customers mark the checkbox to authorize your Application to import their Ring data. After the customers select the Authorize button, your Application will have the capability to import customers’ data. If the Ring customers exit from this page or select Cancel, your Application won’t have the capability to import customers’ data.

🚧 To import customers' data, you will need to complete the steps in the Configure Ring Data Portability service, Authorize your app to connect with Ring Data Portability API, and Connect your app with Ring Data Portability API.

Steps to Onboard with Ring

Step 1: Send an email to ring-data-portability-ipv@amazon.com with the below details to begin the onboarding process: Email address Company Name, Company Address, Name of the Business Owner or Legal Representative Please attach the Business license to the email Step 2: Respond to emails/queries/meeting invites from the Ring/Amazon teams to help kickstart the onboarding process. Step 3: A questionnaire will be shared after validating the above details. Fill the details and share it for further validation. Step 4: Respond to emails/queries during the Third Party Security Assessment until its successful completion. Step 6: Send an email to ring-data-portability@amazon.com to request credentials, and share the TPSA(Third party Security Assessment) ID for reference. Step 5: Enable the customer experience (CX) in the 3P website and app.

Authorize your application to connect to Ring Data Portability for EU DA

Initiating the authorization Flow

After onboarding, you will receive a client_id and client_secret, which are used for subsequent OAuth 2.0 API interactions.

To initiate the authorization flow, direct users to the appropriate authorization endpoint:

• For Ring: GET https://oauth.ring.com/v2/authorize
• For Blink: GET https://api.oauth.blink.com/v2/authorize

This endpoint must be called with an HTTP GET request, with all required parameters provided as form-encoded query parameters. These include:

• client_id: Provided during onboarding
• redirect_uri: The URI to redirect the user after authorization; must match a registered URI from onboarding
• scope: The access scope; use "data-portability"
• code_challenge: The PKCE code challenge (derived from your code verifier)
• code_challenge_method: encryption method used for the code challenge. IE: S256 / plain
• state: An opaque value the client provides to help protect against CSRF. We return it unchanged; it’s up to the client to generate and validate it.

Example Request:

GET https://oauth.ring.com/v2/authorize?
    redirect_uri=<your_redirect_uri>&
    client_id=<your_client_id>&
    response_type=code&
    scope=data-portability&
    code_challenge=<your_code_challenge>&
    code_challenge_method=S256&
    state=<random_state>

When this request is made, the user will be guided through the Ring or Blink login experience. Once complete, the user will be redirected to the specified redirect_uri with two key query parameters appended:

• code: The authorization code, used to request tokens
• state: The same value you originally sent; verify this to ensure request integrity

In the case of any errors that occurs, or if the user cancels the authorization flow during the Ring/Blink login experience, the user will be redirected back to the provided redirect_uri with the following parameters:

https://<your_redirect_url>?error=<error_message>&error_description=<error_description>&state=<your_state_provided_earlier>

An example of when a user cancels the experience will look like the following:

?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request&state=<your_state_from_earlier>

Exchanging Authorization Code for Tokens

To exchange the authorization code for an access token and refresh token, make the following POST request to the token endpoint:

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

Required form parameters:

• grant_type: "authorization_code"
• client_id: Your client ID
• client_secret: Your client secret
• code: The authorization code received from the redirect
• redirect_uri: Must match the original redirect URI
• code_verifier: The original PKCE string that must correspond to the code_challenge, based on the specified code_challenge_method (e.g., plain or S256).
• scope: "data-portability"

Example Response

  {
    "access_token": "<your_access_token>",
    "expires_in": int,
    "refresh_token": "<your_refresh_token>",
    "scope": "data-portability",
    "token_type": "Bearer"
  }

Obtaining New Access Tokens With Refresh Tokens

To obtain a new access token using a refresh token, send a POST request to https://oauth.ring.com/oauth/token with Content-Type: application/x-www-form-urlencoded. This request uses the refresh_token grant type and should include the following required parameters:

• grant_type: "refresh_token"
• refresh_token: the refresh token you previously received
• client_id: your client ID
• client_secret: your client secret
• scope (optional): defaults to the originally requested scopes, (e.g., "data-portability").

If successful, the response will include a new access_token and a new refresh_token. Store the new refresh token if one is returned, as it will replace the old one for future use.

Example:

  POST https://oauth.ring.com/oauth/token HTTP/1.1
  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>

Connect with the Data Portability APIs

Amazon Data Portability lets you import customer data to your Application provided the customers give authorization.

Version information

• Version: 2024-02-29

License information

• License: Amazon Software License
• License URL: https://aws.amazon.com/asl/

Consumes

application/json

Produces

application/json

Endpoints

📘 You have an option to switch anytime between regions because all responses will be synced.

External Docs

• Description : Learn more about Amazon.
• URL : https://developer.amazon.com

Operations

createDataQuery

listDataQueryRecords

📘 Responses for all operations have a five minute, time-to-live (TTL) based on the authorization check. During the five-minute period, the API will return the same response for the same parameters.

Paths

Create Data Query

  POST /{scopeId}/data-queries

Operation:

createDataQuery

Description:

Use the createDataQuery operation to start requesting authorized customer data. The request will start in the Amazon Data Portability API, an async task that will start the request to gather data, and at the same time, will return the queryId that identifies the request from the async task.

To ensure fair usage and system stability, the Create Data Query operation has the following rate limits: Standard base rate: 5 requests per second Burst limits: Up to 5 concurrent requests per second Overall limit: No more than 20 requests within a 20-minute interval

Requests exceeding these limits will be throttled with a 429 HTTP status code.

Parameters:

Only one request for customer and scopeId can be computed at a time. If there’s a request in progress and in a non-terminal state (not COMPLETED or CANCELED), the API will return a CONFLICT error.

Responses

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Amazon Data Portability API returns forbidden or invalid token errors if (1) authorization expired, (2) the customer revoked the authorization, or (3) the account is on hold.

List Data Query Records

  GET /{scopeId}/data-queries/{queryId}/records

Operation:

listDataQueryRecords

Description:

Use the listDataQueryRecords operation to view all customer data and port it in your Application. Use this operation for queries that have been marked with COMPLETED status. For queries that have a different status, the API will return an error.

List Data Query Records will return results for a query after the notification response has been sent. Each file and schema link will be available for five minutes from the time the response was sent, and you can perform the same list operation for the same query for at most 1 hour after the response notification has been sent. All schemas and responses from a List Data Query Record, after download, will be at 2GB max.

To ensure fair usage and system stability, the List Data Query operation has the following rate limits: Standard base rate: 10 requests per second Burst limits: Up to 5 concurrent requests per second Daily quota: 100,000 requests

Requests exceeding these limits will be throttled and receive a 429 HTTP status code.

Parameters

Responses

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Amazon Data Portability API returns forbidden or invalid token errors if (1) authorization expired, (2) the customer revoked the authorization, or (3) the account is on hold.

Response Notification

Description:

Once the create data query has reached its final state, Amazon Data Portability API sends a notification response, through a POST method, on your HTTPS endpoint. The API sends the response to the same region you sent the create request. The notification file size is at 1KB max. You can perform List Data Query Records operations for the same query for at most 1 hour after the response notification has been sent.

Amazon Data Portability API includes the notification version number in the response. Consider including the version number at the end of the HTTP path. For example, if your HTTPS endpoint is https://myapp/notifications, use https://myapp/notifications/v1 for version 1.

Available supported versions: 1.0 Latest supported version: 1.0

📘 You have an option to change the HTTPS endpoints by submitting a case through a Contact Us in Developer Portal. In the category section, select "Amazon Data Portability". In the topic section, select "Allowlisting & Integration Updates". Provide the details related to your new HTTPS endpoints.

Responses:

The notification has the HTTP/HTTPS notification JSON format.

📘 The Application is automatically subscribed to the notification version number available during Application submission. After Application submission, and if a new notification version becomes available, you have an option to request for the new version.

To opt-in to a new version, go to Contact Us in the Developer Portal. In the Category section, select "Amazon Data Portability". In the Topic section, select "Allowlisting & Integration Updates". Provide details related to your HTTPS endpoints.

Error Responses and Schemas

The Application must handle any standard HTTP response code that could result from a web service call. All APIs return an HTTP response code of 200 or 201 if the call was successfully received and processed. Any errors that occurred during processing are detailed in the response with corresponding status code.

These are all known errors that can be returned. If you encounter an error not present in the table, start by retrying the error. If the error persists, sign in to your Amazon Developer account. Go to Contact Us. In the Category section, select "Amazon Data Portability". In the Topic section, select "Technical Issues".

Retrying errors:
By default, the API has no retry configuration added. If you received a response with 429, 500, or 504 HTTP status code, make a retry request. If you want to retry multiple times, we recommend that you implement an exponential backoff approach up to a defined limit, and then log the error and proceed with a manual follow-up and investigation. For example, time your retries in this time intervals: 1s, 2s, 4s, 10s, and 30s. The actual backoff times and limit depends on your business processes.