Self Serve Testing

Overview and Prerequisites

Self Serve Testing allows third-party developers to validate their integration flows during the Data Portability app onboarding process. The testing environment simulates production conditions, allowing you to identify and resolve integration issues early.

Prerequisites

• Pre-approval confirmed: Pre-approval form must be confirmed by Meta.
• OAuth information: Your OAuth server and token endpoints must be accessible and functional according to the information you provided in the OAuth information form.

What you can test

• OAuth server redirect - OAuth 2.0 Authorization Code flow implementation
• OAuth access token - Access token generation
• OAuth refresh token - Refresh token functionality
• OAuth revoke token - Token revocation processes (if supported)

Important

• This testing tool does not affect your overall onboarding progress - it's for integration validation and debugging only.
• Meta does not store any sensitive data (such as tokens) from your testing session, and your testing session is limited to your browser tab. Therefore, you'll need to restart if you reload or close the browser tab.

Tips and Guidelines

• Testing session: Our system does not store any sensitive information from your testing session, such as tokens or authorization codes. Therefore, if you reload the page, you'll need to start fresh, which you can easily do as mentioned in the next point.
• Fresh start: Run the first testing flow (OAuth server redirect) to restart the entire testing session with a new authorization code.
• Status pills: Success, Error and Unavailable status pills are used to notify the status of a test. You can hover over these pills to view useful messages in the tooltip.
• Generic error: If you see an Error pill with a generic error message "An error occurred", contact us for help.
• Check logs: Monitor your server logs during testing to identify specific issues.
• Verify configuration: Double-check OAuth URLs, Client ID, and Client Secret in your app settings.

Getting Started

Accessing the Testing Tool

1. Navigate to your Data Transfer app dashboard on developers.facebook.com.
2. Click "Test use cases" from the dashboard, or select "Testing" from the navigation bar.
3. The testing section will appear as shown below:
   
4. The "Start testing" button will not work if your pre-approval form is not confirmed or OAuth information form is not submitted successfully. In that case, you will see a tooltip on the button with a message: "Your app must be approved and OAuth information form submitted to continue".
5. If your pre-approval form is confirmed, you can click the "Start testing" button to begin testing the integration flows.

Testing flows

As you click on the "Start testing" button, you will see a list of Testing flows which you can run to verify integration of your app. Following is a brief overview of these testing flows:

OAuth server redirect

Purpose

Validates that Meta can successfully redirect users to your OAuth authorization server, receive an authorization code, and be redirected back to the Testing page.

How it works

1. Click Test to initiate the OAuth server redirect flow.
2. You'll be redirected to your OAuth server endpoint (the URL you provided in the "OAuth URL" field of the OAuth information form).
3. This flow works as described in the OAuth 2.0 Authorization Code Flow, with the specified parameters sent as the query parameters.
4. After authorization, you redirect back to the testing page with an authorization code.

Status indicators

• In case of success, a Success pill appears in the lower left corner of the test card as shown above. You can hover over such a status pill to see the relevant message.
• In case of error, an Error pill appears.

Debugging tip: If needed, use the OAuth server url hyperlink in the test card description to preview the complete generated URL before being redirected by clicking the Test button.

OAuth access token

Purpose

Verifies that Meta can exchange the authorization code for an access token using your token endpoint.

Prerequisites

• OAuth server redirect testing flow must be completed successfully as the authorization code received in OAuth server redirect step will be used here to call the OAuth token endpoint.

If the prerequisites are not met, this test flow will show an Unavailable pill in the lower left side as can be seen in the screenshot above. At this point, the Test button will not work.

How it works

1. Click Test to initiate the flow that exchanges the authorization code for an access token.
2. The endpoint used here is the one you provided in the field "Access Token URL" while filling out the OAuth information form.
3. This flow works as per the exchange logic described in the OAuth 2.0 Authorization Code Flow.

Status indicators

• In case of success, a Success pill appears with the following response information in tooltip as shown above:
  • Access token: "Successfully received"
  • Refresh token: "Successfully received" or "Not received" based on whether refresh token was present in response.
  • Scope: Space-separated scope strings returned by your endpoint.

• In case of error, an Error pill appears. If the error was caused by your endpoint, the response message should appear in the tooltip as shown above. If the error did not occur at your endpoint and the tooltip shows something generic like "An error occurred", contact us for help.

OAuth refresh token

Purpose

Tests your server's ability to refresh access tokens using refresh tokens, enabling recurring data transfers.

Prerequisites

• OAuth access token testing flow completed successfully along with a valid refresh token received.

Like the previous testing flow, this test flow will show an Unavailable pill in the lower left side as can be seen in the screenshot above if the prerequisites are not met. At this point, the Test button will not work.

How it works

1. Click Test to initiate the flow.
2. This uses the same endpoint as the OAuth access token testing flow. The request parameters are slightly different, as shown in the screenshot below. Refer Refreshing Access Tokens for more context.
   

Status indicators

• In case of success, a Success pill appears with the following response information in tooltip as shown above:
  • Access token: "Successfully updated"
  • Refresh token: "Successfully updated" or "Not received" based on whether refresh token was present in response.
• In case of error, an Error pill appears with a relevant message as explained in the previous testing flow.

Important notes

• If no new refresh token is returned in response to the refresh token call, the old refresh token will continue to be used for subsequent calls.
• Having a refresh token functionality is critical for recurring transfers (daily/monthly/yearly data transfers).

OAuth revoke token (if supported)

Purpose

Validates that Meta can properly revoke access tokens when data transfers are complete, ensuring security and compliance.

Availability

This testing flow only appears if you provided a valid value in the field "Access Token Revocation URL" of your OAuth information form. If no revocation URL was provided, this step will be hidden.

Prerequisites

• OAuth access token testing flow completed successfully.

How it works

1. Click Test to initiate the flow and call your Access Token Revocation URL endpoint.
2. For token revocation we use a POST request as shown in the curl command below:
   

   curl -X POST <Access Token Revocation URL>  --header "Authorization: Bearer <access token>" --header "Content-Type: application/json"

3. Your server should invalidate the token and return success.

Status indicators

• In case of success, a Success pill appears as shown above. You can now execute the OAuth refresh token testing flow again and expect an error, confirming that the tokens were revoked properly.
• In case of error, an Error pill appears with a relevant message as explained in the previous testing flows.