Skip to main content

Testing Endpoints

Testing Only

The API endpoints and associated commands are to be used for test purposes only. The example requests provide the ability to manually simulate requests being sent from DataGrail to your internal systems integration implementation.

To avoid impacting production requests and data during this time, your internal systems implementation should not be integrated with DataGrail nor production internal systems.

Usage

Some endpoints are unique to the Internal Systems Agent and are not included in the API Specification.

To use these endpoints for testing, make HTTP requests using your preferred client or library (e.g. cURL, Postman).

If you are using the Agent, an OpenAPI Swagger interface is available at https://{base-url}/docs.

Base URL

All endpoints use the same base URL and should be secured with HTTPS (TLS v1.2 or above):

https://{base-url}

Example: if the base URL is datagrail-production.company-name.com and the endpoint is /api/v1/token, the request URL would be:

https://datagrail-production.company-name.com/api/v1/token

Authentication

All requests to Internal Systems endpoints must include an Authorization header with Bearer authentication:

Authorization: Bearer {access-token}

Authentication Methods

  • OAuth 2.0 - For more information, see how to retrieve a token.
  • Static Token - API only - This token will be used for all requests to the API.

Confirm Agent Running

GET /

Confirms the Agent is running and accessible.

If you're testing locally and unable to access the Agent, check the ingress firewall rules (e.g. Agent ingress restricted to only DataGrail's IP).

Agent Only

This endpoint is only applicable to the Agent, and is not required for an API implementation.

Request

curl -X 'GET' 'https://{base-url}/' \
-H 'accept: application/json'

Response

200 Agent is running.

{
"version": "v1"
}

Authenticate and Retrieve Token

POST /api/v1/token

Requests an OAuth 2 access token for use in subsequent calls.

Parameters

Header Parameters

Authorization (string, required)

Value format: Basic {Base64 encoded client_id:client_secret}

If using the Agent, use the same client_id and client_secret values referenced in Configuration.

Example: If the values of client_id and client_secret are the same as the keys, then the result of Base64 encoding client_id:client_secret will be Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=.

The final parameter value will then be Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Body Parameters

grant_type (string, required)

Value set to client_credentials

Request

curl -X 'POST' 'https://{base-url}/api/v1/token' \
-H 'Authorization: Basic {Base64 encoded client_id:client_secret}' \
-d 'grant_type=client_credentials'

Response

200 Access token retrieved. Use this value in subsequent requests.

{
"access_token": "dga_$abcdefghijklmnopqrstuvwxyz0123456789",
"expires_in": "1800",
"token_type": "Bearer"
}

401 Unauthorized - An invalid authentication signature was provided, or the authentication signature was missing.

{
"detail": "Invalid authentication credentials"
}

List Available Connections

GET /api/v1/connections/list

Returns an array of internal connections available for processing requests.

Request

curl -X 'GET' 'https://{base-url}/api/v1/connections/list' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}'

Response

200 List of connections retrieved.

{
"results": [
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "Postgres",
"name": "Accounts DB",
"mode": "live",
"capabilities": [
"privacy/access",
"privacy/delete",
"privacy/identifiers"
]
}
]
}

Perform All Health Checks

GET /api/v1/hc

DataGrail will call this endpoint to test that the credentials provided are valid and the service is healthy.

Request

curl -X 'GET' 'https://{base-url}/api/v1/hc' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}'

Response

200 All connections healthy.

{
"Status": "OK",
"ConnectorStatuses": [
[
{
"Status": "Success",
"connection_uuid": "12345678-abcd-1234-abcd-123456abcdef",
"connection_type": "Postgres"
}
]
]
}

400 Bad Request - Check response to identify the failed connector. For further detail, review the Agent container logs or API application logs.

{
"detail": {
"Status": "Failed",
"ConnectorStatuses": [
{
"Status": "Failure",
"connection_uuid": "12345678-abcd-1234-abcd-123456abcdef",
"connection_type": "Postgres"
}
]
}
}

Perform Single Health Check

GET /api/v1/hc/{connection-uuid}

Checks a connection to confirm working correctly.

Agent Only

This endpoint is only applicable to the Agent, and is not required for an API implementation.

Parameters

Path Parameters

connection-uuid (string, required)

UUID associated with the system connection for this request.

Request

curl -X 'GET' 'https://{base-url}/api/v1/hc/{connection-uuid}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}'

Response

200 Connection is healthy.

{
"Status": "OK",
"ConnectorStatuses": [
[
{
"Status": "Success",
"connection_uuid": "12345678-abcd-1234-abcd-123456abcdef",
"connection_type": "Postgres"
}
]
]
}

400 Bad Request - Connection failed. Review the Agent container logs for further detail.

{
"detail": {
"Status": "Failed",
"ConnectorStatuses": [
{
"Status": "Failure",
"connection_uuid": "12345678-abcd-1234-abcd-123456abcdef",
"connection_type": "Postgres"
}
]
}
}

Submit an Access Request

POST /api/v1/privacy/access/{connection-uuid}

Initiate an access request for the passed connection.

Parameters

Path Parameters

connection-uuid (string, required)

UUID associated with the system connection for this request.

Body Parameters

callback_path (string, required)

URL path used when triggering results callback. Begins with forward slash.

identifiers (object, required)

JSON object containing values to identify the data subject’s personal data.

request_uuid (string, required)

UUID of the subject request.

results_token (string, required)

Hexadecimal string (length: 32) used to retrieve the results of this request.

Request

curl -X 'POST' 'https://{base-url}/api/v1/privacy/access/{connection-uuid}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json' \
-d '{
"identifiers": {
"email": [
{
"email": "frank@acme.com"
}
]
},
"callback_path": "/",
"request_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afdf",
"results_token": "11a45350f9c03c4080487271c5d5ad7b"
}'

Response

200 Access request accepted and queued for processing.

{
"Status": "Access Job with id 11a45350f9c03c4080487271c5d5ad7b enqueued"
}

Submit a Deletion Request

POST /api/v1/privacy/delete/{connection-uuid}

Initiate a deletion request for the passed connection.

Parameters

Path Parameters

connection-uuid (string, required)

UUID associated with the system connection for this request.

Body Parameters

callback_path (string, required)

URL path used when triggering results callback. Begins with forward slash.

identifiers (object, required)

JSON object containing values to identify the data subject’s personal data.

request_uuid (string, required)

UUID of the subject request.

results_token (string, required)

Hexadecimal string (length: 32) used to retrieve the results of this request.

Request

curl -X 'POST' 'https://{base-url}/api/v1/privacy/delete/{connection-uuid}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json' \
-d '{
"identifiers": {
"email": [
{
"email": "frank@acme.com"
}
]
},
"callback_path": "/",
"request_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afdf",
"results_token": "11a45350f9c03c4080487271c5d5ad7b"
}'

Response

200 Deletion request accepted and queued for processing.

{
"Status": "Deletion Job with id 11a45350f9c03c4080487271c5d5ad7b enqueued"
}

Submit an Identifier Retrieval Request

POST /api/v1/privacy/identifiers/{connection-uuid}

Perform an identifier retrieval request for the passed connection. This request is synchronous and must return results in the response.

Identifiers are verifiable keys that allow the systems to uniquely identify a data subject within a specific context like a data system or an organization. Data subjects can be linked to multiple identifiers.

Parameters

Path Parameters

connection-uuid (string, required)

UUID associated with the system connection for this request.

Body Parameters

identifiers (object, required)

JSON object containing values to identify the data subject’s personal data.

request_uuid (string, required)

UUID of the subject request.

Request

curl -X 'POST' 'https://{base-url}/api/v1/privacy/identifiers/{connector-uuid}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json' \
-d '{
"identifiers": {
"email": [
{
"email": "frank@acme.com"
}
]
},
"request_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

Response

200 Identifier retrieval completed.

{
"phone_number": [
{
"phone_number": "8885551234"
}
]
}

200 No identifier found.

{
"phone_number": []
}

Submit an Opt-Out Request

POST /api/v1/privacy/optout/{connection-uuid}

Perform an opt-out or Do Not Sell/Share request for the passed connection. This request is synchronous and will return the success/failure of the operation.

Parameters

Path Parameters

connection-uuid (string, required)

UUID associated with the system connection for this request.

Body Parameters

identifiers (object, required)

JSON object containing values to identify the data subject’s personal data.

Ignore Additional Parameters

The following body parameters are included in the body of the request from DataGrail, however they can be ignored: results_token, request_uuid, and callback_path.

Request

curl -X 'POST' 'https://{base-url}/api/v1/privacy/optout/{connector-uuid}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/json' \
-d '{
"identifiers": {
"email": [
{
"email": "frank@acme.com"
}
]
}
}'

Response

200 Opt out request completed.

{
"status": "completed"
}

 

Need help?
If you have any questions, please reach out to your dedicated CSM or contact us at support@datagrail.io.

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.