Segment Public

Authentication & Authorization

Credentials

• Segment Public uses token-based authentication, allowing users to authenticate API requests by inputting their tokens into the HTTP authorization bearer token header.
• Segment Public workspace API token can be obtained from the Segment App (see Segment Public Connection Instructions).
• Optionally, integration can be configured to support Segment Profile API:
  • Segment Profile API uses basic authentication for authorization with the Access Secret as the authorization key and Space ID that should be passed into the Profile API request URLs.
  • Access Secret and Space ID can be obtained from the Segment App (see Segment Public Connection Instructions).
• Publicly exposing your API credentials can allow unauthorized access to the Segment Public API endpoints, and your Segment data by a third party. DataGrail stores your API credentials encrypted and protected.

Permissions

• Each Segment Workspace requires a separate token (see Segment Public Connection Instructions).
• If Segment Profile API is configured, Access Secret must be assigned to the Workspace Owner.

Base URL

The Segment Public API can be accessed through multiple regions, depending on data residency policies. And the base API URL (BASE_URL) depends on the region:

• For US-based Workspaces: https​://api.segmentapis.com
• For EU-based Workspaces: https​://eu1.api.segmentapis.com

Segment Profile Base URL

The Segment Profile API can be accessed through multiple regions, depending on data residency policies. And the base API URL (SE_BASE_URL) depends on the region:

• For US-based Workspaces: https:​//profiles.segment.com/v1/spaces
• For EU-based Workspaces: https:​//profiles.euw1.segment.com/v1/spaces

Endpoints Utilized

DataGrail uses the following endpoint to validate that credentials are good based on a successful response and workspace ID:

• GET {BASE_URL}/

Optionally, If Segment Profile API is configured, DataGrail uses the following endpoint to validate that credentials are good based on a successful response:

• GET {SE_BASE_URL}/{space_id}/collections/users/profiles/

Version

DataGrail integration currently supports Segment Public REST API version 1 (v1) and Segment Profile API version 1 (v1).

Limits

The most common Segment causes for rate limits include, but are not limited to:

• Too many requests made against a resource in a short period of time.
• Requesting a large page count or too many pages in a paginated resource too quickly.

Rate limited requests fail with the 429 status code. DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

Access

For an access request, DataGrail will take the following actions:

• Search IAM users by the Data Subject email:
  • Fetch list of users with access to the Workspace.
  • Select users by the Data Subject identifiers (email or user ID).
  • Fetch user details by ID for all collected users.
• If Segment Profile API is configured:
  • Fetch Profile’s Events by the Data Subject identifiers (email or user ID).
  • Fetch Profile’s Traits by the Data Subject identifiers (email or user ID).
• For all objects found, DataGrail will return all available fields. You can edit which objects and fields you want to provide to the Data Subject via our Portal Requests.

Endpoints Utilized

• GET {BASE_URL}/users
• GET {BASE_URL}/users/{userId}

Optionally, If Segment Profile API is configured:

• GET {SE_BASE_URL}/{space_id}/collections/users/profiles/{DSR_IDENTIFIER}/events
• GET {SE_BASE_URL}/{space_id}/collections/users/profiles/{DSR_IDENTIFIER}/traits

note

DataGrail also supports the Direct Contact Access workflow for Segment Public integration.

Deletion

For a deletion request, DataGrail will take the following actions:

Step 1. Request deletion a customer’s personal data

On the first step DataGrail is trying to get the user ID required for deletion requests on Step 2.

• If Segment Profile API configured:
  • Search user id through external IDs by the Data Subject email.
• Search IAM users by the Data Subject email:
  • Fetch list of users with access to the Workspace.
  • Select users by the Data Subject email.

Step 2. Deleting a customer’s personal data

• Create Workspace Regulation with "DELETE_ONLY" type and “USER_ID” subject type to delete all collected users by ID.
• Get regulation from the Workspace to check the current status of the deletion request.
• Complete processing when overall status is "FINISHED".

Endpoints Utilized

• GET {BASE_URL}/users
• POST {BASE_URL}/regulations
• GET {BASE_URL}/regulations/{regulation_id}

Optionally, If Segment Profile API is configured:

• GET {SE_BASE_URL}/{space_id}/collections/users/profiles/{DSR_IDENTIFIER}/external_ids

note

DataGrail also supports the Direct Contact Deletion workflow for Segment Public integration.

Do Not Sell

For a Do Not Sell request, DataGrail will take the following actions:

• Create Workspace Regulation with "SUPPRESS_ONLY" type and “USER_ID” subject type to suppress requested user by ID.

Endpoints Utilized

• POST {BASE_URL}/regulations

System Detection

DataGrail reads Segment Public sources, destinations and warehouses to detect new systems connected to Segment account.

For an system detection requests, DataGrail will take the following actions:

• Fetch list of sources.
• Fetch list of destinations.
• Fetch list of warehouses.

Endpoints Utilized

• GET {BASE_URL}/sources
• GET {BASE_URL}/destinations
• GET {BASE_URL}/warehouses