Integrating Internal Systems (OAuth)

Capabilities

DataGrail's Internal Systems (OAuth) integration provides the following capabilities:

Product	Capability
Request Manager	Request Types Access, Deletion, Do Not Sell/Share, Identifiers Identifier Categories Any

Before You Start

To successfully configure this integration, please ensure you have sufficient privileges:

• DataGrail User Role: Super Admin, Connections Manager
• Internal Systems (OAuth) User Role: Admin

Confirm that your deployment is securely configured:

• Network Ingress Rules: Allow inbound traffic only on port 443 (HTTPS) from DataGrail's VPC IP 52.36.177.91. All other sources should be denied access to this port.

warning

Once configured, this integration will be added to all new privacy requests!

If requests are already being processed DataGrail, confirm the following before continuing:

• Testing has been completed
• Changes coordinated with your team

Connect to DataGrail

1. In DataGrail, navigate to Integrations and select Configure New Integration to search for Internal Systems (OAuth).
2. Enter an Integration Name that includes additional context like hosting platform and environment (e.g. AWS Test us-west-2).
3. Under Enabled Identifiers, select only the applicable identifiers that the system is configured to receive. If you are unsure, only select Email.
4. Enter the API Token Endpoint URL that DataGrail will use to initiate the OAuth flow. It must begin with https://. If you are using the Request Manager Agent, the endpoint will be {your-api-base-url}/api/v1/token.
5. Enter the Client ID and Client Secret OAuth credentials you created for DataGrail to authenticate with the API.
6. Enter the API Base URL to use for all API requests. It must begin with https:// (e.g. https://datagrail.acme.com).
7. Select the Data Retrieval behavior for deletions.
   warning

   When using Retrieve Data, the data reviewed may not be exactly what is deleted due to the access and deletion logic executing separately!

8. Select Configure Integration to connect.
   Investigating Failed Connections

   If the connection fails, an error toast will appear, providing options to review the request and response details. Note that for security reasons, 500-level errors will not include a response body. To investigate further, check the logs of the Agent container for additional information.

Next Steps

Now that you've successfully connected the integration, check out the following resources:

• Synchronous vs. Asynchronous Integrations
• Whole Record Deletion
• Access Request Lifecycle
• Deletion Request Lifecycle

Troubleshooting

If you are unable to successfully connect the integration, review these common troubleshooting steps:

Ensure that DataGrail is able to reach the service

After configuring the integration, DataGrail will make requests to the API. If you do not see a request in your application logs, check the following:

• In DataGrail, was the correct API Base URL entered?
• Within your infrastructure, check the perimeter logs (e.g. Application Load Balancer) to see if the request was received and forwarded to the service.

Request Manager Agent: Confirm that the service is running and healthy

Check the logs of your container orchestration service where the agent was deployed (e.g. AWS ECS):

• Is the service active?
• Is the service healthy? If not, review the agent logs to determine the cause.

Ensure the OAuth credentials are correct and accessible

Before DataGrail sends a request to the API, a token will be requested from the provided API Token Endpoint URL. Check your application logs for additional information.

If you are using the Request Manager Agent...

Upon receiving the request from DataGrail, the agent will first retrieve the configured credentials from the credentials manager.

If your agent logs indicate a request could not be authenticated:

• Confirm that the credentials are properly formatted in your credentials manager.
• Confirm that the correct Client ID and Client Secret were used to configure this integration in DataGrail.

If your agent logs indicate an issue exists retrieving credentials:

• Confirm that the location of the credentials (e.g. ARN) in the agent configuration is correct.
• Confirm that agent IAM policy has the necessary permissions to retrieve the credentials.

If you are using the ISI API Specification...

• Check the logs of the configured OAuth token provider for errors.
• Confirm that the correct Client ID and Client Secret were used to configure the integration in DataGrail.

Technical Details

Access Type	Asynchronous
Deletion Type	Asynchronous (Whole Record)
Opt Out Type	Synchronous

API Documentation

Learn more about this API implementation by selecting the integration method:

• Request Manager Agent
• Internal Systems API Specification