Testing Endpoints
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.
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).
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
andclient_secret
values referenced in Configuration.Example: If the values of
client_id
andclient_secret
are the same as the keys, then the result of Base64 encodingclient_id:client_secret
will beY2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
.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.
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.
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"
}
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.