Navbar
shell java c# ruby python javascript

Introduction

Welcome to the Ethyca System Documentation and API Developer Docs.

Ethyca is Privacy Infrastructure for developer teams to automate compliance with and management of User Data Privacy. We design and build software that makes it easier for you and your teams to build products for your users that do the right thing at all times with their data; keeping you and your users safer and ensuring trust in data-driven businesses.

Ethyca is structured as a primary application service and a series of Proxy adaptors and extensions that intermediate data transactions throughout your environment. This system design minimizes change in your stack while maximally controlling and managing data privacy requirements for you.

Please note, this is partial sample documentation only, complete docs are available as part of our Beta Developer and Pilot Enterprise programs. Contact Us to get your full access now.

We have language for Shell, Java, Ruby, Python, and JavaScript. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Any other questions, please either get in touch or check our growing support center

Authentication

To authorize, use this code:

require 'ethyca'

api = Ethyca::APIClient.authorize!('sGCtYR65stXqnrgYn35XuqVTilSWWhRc')
import Ethyca

api = ethyca.authorize('sGCtYR65stXqnrgYn35XuqVTilSWWhRc')
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: sGCtYR65stXqnrgYn35XuqVTilSWWhRc"
const ethyca = require('ethyca');

let api = ethyca.authorize('sGCtYR65stXqnrgYn35XuqVTilSWWhRc');

Make sure to replace sGCtYR65stXqnrgYn35XuqVTilSWWhRc with your API key.

Ethyca uses API keys to allow access to the API. New Ethyca API key are granted to users from within the Ethyca Control Panel, which must be configured prior to testing integrations here. Access Control Info.

Ethyca expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: sGCtYR65stXqnrgYn35XuqVTilSWWhRc

Subject Rights Controller

Delete User

This endpoint downloads a binary file for a given entity ID.

HTTP Request

GET http://ethyca-example.com/api/user/delete

Declaration

Method Response Content type Description
POST Request to execute the right to delete (for specific attributes of entity)

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
formData entityId yes entityId 84e16258-3076-4a09-8052-66920211da5a
formData attributeNames yes Full qualified attribute names orders.shipping_address,orders.shipping_status

Responses

Code Description Example
200 OK Here
400 Request with bad parameters Invalid table attribute name format: orders.shipping.status. (ex. orders.shipping_status)
401 Invalid API Key Invalid API key
404 End user not found No entity found by ID: 84e16258-3076-4a09-8052-66920211da5a

Forget User

This endpoint downloads a binary file for a given entity ID.

HTTP Request

GET http://ethyca-example.com/api/user/forget

Declaration

Method Response Content type Description
POST Request to execute the right to forget (complete erasure)

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
formData entityId yes entityId 84e16258-3076-4a09-8052-66920211da5a

Responses

Code Description Example
200 OK Here
401 Not authorized to perform Invalid API key
404 End user not found No entity found by ID: 84e16258-3076-4a09-8052-66920211da5a

Execute SAR (Subject Access Request)

This endpoint starts an automated SAR, retrieving all related users personal information.

HTTP Request

GET http://ethyca-example.com/api/user/sar

Declaration

Method Response Content type Description
POST Subject access request

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
formData entityId yes entityId 84e16258-3076-4a09-8052-66920211da5a
formData email yes email no-reply@ethycaissafe.com

Responses

Code Description Example
200 OK Here
401 Not authorized to perform Invalid API key
404 End user not found No entity found by ID: 84e16258-3076-4a09-8052-66920211da5a

Entity Controller

Create Entity

Request body structure in JSON:

[ {
  "error" : { },
  "name" : "Orders",
  "references" : [ {
    "error" : { },
    "parentId" : "0cc4ba38-f3c8-4537-ae40-17a838ec0438",
    "parentName" : "Customers"
  } ],
  "attributes" : [ {
    "name" : "Order Date",
    "value" : "2019-04-28T15:47:08.364"
  }, {
    "name" : "Order Status",
    "value" : "Shipped"
  } ]
}, {
  "error" : { },
  "name" : "Orders",
  "references" : [ {
    "error" : { },
    "parentId" : "0cc4ba38-f3c8-4537-ae40-17a838ec0438",
    "parentName" : "Customers"
  } ],
  "attributes" : [ {
    "name" : "Order Date",
    "value" : "1234567"
  }, {
    "name" : "Order Status",
    "value" : "Completed"
  } ]
} ]

This endpoint retrieves a specific entity.

HTTP Request

GET http://ethyca-example.com/api/entity/create

Declaration

Method Response Content type Description
POST application/json Create entities

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
body Request body yes Array of entities to create Here

Responses

Code Description Example
203 Created Here
400 Bad Request Here
401 Invalid API Key Here

Delete Entity

Request body structure in JSON:

[ "60bf2ee3-7ea4-4416-93ba-873d15e5cf4d", "1ab64b6a-9418-445f-89ea-01573eb1c094" ]

This endpoint deletes a specific entity.

HTTP Request

GET http://ethyca-example.com/api/entity/delete

Declaration

Method Response Content type Description
POST application/json Delete entities along with their attributes

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
body Request body yes Array of entities to create Here

Responses

Code Description Example
200 OK Here
400 Bad Request Here
401 Invalid API Key Here

Delete Attribute

Request body structure in JSON:

[ {
  "id" : "e3ee4521-b518-4dde-a3b1-518537841d09",
  "error" : { },
  "attributes" : [ {
    "name" : "Order Date"
  }, {
    "name" : "Order Status"
  } ]
}, {
  "id" : "8069cf1c-6264-4e63-94ab-3bd5e432d484",
  "error" : { },
  "attributes" : [ {
    "name" : "Order Date"
  }, {
    "name" : "Order Status"
  } ]
} ]

This endpoint deletes a specific attribute.

HTTP Request

GET http://ethyca-example.com/api/attribute/delete

Declaration

Method Response Content type Description
POST application/json Delete entity attributes. Entities themselves stay

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
body Request body yes Array of entities. Populated entity attributes will be deleted Here

Responses

Code Description Example
200 OK Here
400 Bad Request Here
401 Invalid API Key Here

Update Attribute

Request body structure in JSON:

[ {
  "id" : "b3f75050-0946-4420-bdc6-1ab0244cc1b3",
  "error" : { },
  "attributes" : [ {
    "name" : "Order Date",
    "value" : "2019-04-28T15:47:08.526"
  }, {
    "name" : "Order Status",
    "value" : "Shipped"
  } ]
}, {
  "id" : "42d50bc2-b6a1-4b13-80b5-1c37e2b03121",
  "error" : { },
  "attributes" : [ {
    "name" : "Order Date",
    "value" : "2019-04-19T15:47:08.526"
  }, {
    "name" : "Order Status",
    "value" : "Completed"
  } ]
} ]

This endpoint updates a specific attribute.

HTTP Request

GET http://ethyca-example.com/api/attribute/update

Declaration

Method Response Content type Description
POST application/json Update entity attribute

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
body Request body yes Request body Here

Responses

Code Description Example
200 OK Here
400 Bad Request Here
401 Invalid API Key Here

Get Entity by ID

Request body structure in JSON:

[ "64eb526a-077e-43a7-bee3-f6676ba3f8a2", "eba22da9-3b2a-42d8-9add-e2c79da25217" ]

This endpoint retrieves entity for given ID.

HTTP Request

GET http://ethyca-example.com/api/entity/get-by-id

Declaration

Method Response Content type Description
POST application/json Retrieve entities by their IDs

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
body Request body yes Request body Here

Responses

Code Description Example
200 OK Here
400 Bad Request Here
401 Invalid API Key Here

Get Entity by Identity

Request body structure in JSON:

[ "j_smith@gmail.com" ]

This endpoint retrieves entity by identity (as distinct from ID), such as email or username.

HTTP Request

GET http://ethyca-example.com/api/entity/get-by-identity

Declaration

Method Response Content type Description
POST application/json Retrieve entities by their identities

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
body Request body yes Request body Here

Responses

Code Description Example
200 OK Here
400 Bad Request Here
401 Invalid API Key Here

File Controller

Download File

This endpoint downloads a binary file for a given entity ID.

HTTP Request

GET http://ethyca-example.com/api/file/download

Declaration

Method Response Content type Description
POST application/json Download a file

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
query entityID yes entityID Here
query attributeName yes attributeName Profile

Responses

Code Description Example
200 OK Here
400 Errors in request Here

Upload File

Request body structure in JSON:

{
  "entityId" : "f9ff973b-8c77-48d4-ac5d-47b18b629ef6",
  "name" : "Profile",
  "value" : "profile_image2902946665070788237.png"
}

This endpoint downloads a binary file for a given entity ID.

HTTP Request

GET http://ethyca-example.com/api/file/upload

Declaration

Method Response Content type Description
POST application/json Upload a file

Parameters

Type Name Mandatory Description Example
header datastore yes datastore northwind
header api-key yes api-key sGCtYR65stXqnrgYn35XuqVTilSWWhRc
multiPart attribute yes Json string of attribute object Here
multiPart file yes The file to upload File payload

Responses

Code Description Example
200 OK Here
400 Errors in request Here

Responses

The Ethyca API uses the following common response codes:

Code Meaning
200 OK -- Your request has been completed correctly.

Errors

The Ethyca API uses the following error codes:

Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You do not have permission to perform the request.
404 Not Found -- The specified end user (subject) was not found.
429 Too Many Requests -- you have hit the rate limit for the free or tier limited service.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.