Ethnio API Overview & Tips

The Ethnio API allows Enterprise customers to send automated Erasure, Opt Out, and Data Subject Requests via API. All the details for this are located here at ethn.io/api

  1. Erasure
  2. Opt Out - note that if you send opt out emails to Ethnio that do not exist in your Pool, we will return a "non-existing" message and not store those emails.
  3. Data Subject Requests
  4. Import

To help with getting started, we've included some sections below, with the following highlights:

Tips on Getting Started: Generate the Token

There are a number of technical steps that can be tricky as part of the initial process of using the Ethnio API. This includes everything from initial authorization and credentials to understanding the syntax. 

Credentials (Owner or Admins Only)

For security reasons, only the account owner or an admin can generate credentials. Head to Ethnio Account >> Integrations >> Ethnio API, and click “Connect”

 

Once on the page below, click “Generate Credentials” to get the private key and issuer. Note: these credentials display one-time only, so you will need to store them somewhere carefully and securely. There is no way to recover them.

mceclip1.png

Next, you will need to generate your token which will be used to access the API with a timestamp.

Timestamp

Generate a timestamp for your token. This is a best practice for data security.
You can use this free online tool Unix Timestamp.

We recommend generating the timestamp for the next day. You can do this by adjusting the “Day” field to be the next day and then click convert. See below.

 

Web Token

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. 

You can use the tool JWT: https://jwt.io/

From this site, scroll down to Debugger and set the Algorithm to RS512 (sec 1. below). 

Then add your details to the Decoded (Payload and Your Signature) sections below (sec 2 and 3), and the web token will be generated in the “Encoded” section for you to copy. 

Decoded Section: Payload (sec 2)

Past the following text in the Payload section, deleting the content already there.

<span style="font-weight: 400;">{</span><br><br><span style="font-weight: 400;">  "iss": "</span><strong>your issuer field from the Ethnio"</strong><span style="font-weight: 400;">,</span><br><br><span style="font-weight: 400;">  "exp": </span><strong>your timestamp</strong><br><br><span style="font-weight: 400;">}</span>

Once you have pasted this text, you will need to update it with the timestamp you generated above, and the issuer field from the Ethnio app (example below). If you need to troubleshoot at all, please reference this screenshot:

image-2.png

Decoded Section: Verify Signature (sec 3a. & 3.b)

Next, add the Private Key you copied for the Ethnio app and paste it in BOTH fields (sec 4.a and 4.b in the screenshot above).

Encoded section

Copy the results in the encoded section to your clipboard. This is your web token.

API Platform

You’ll need to use an API platform to send delete requests to the Ethnio API. We recommend using Postman, which you can download here: https://www.postman.com Note: the web version of Postman is also available if preferred. Once you have access to the platform open a new tab to start by clicking the “+” symbol.

 

OAuth Token

To add the OAuth token follow the steps below:

  1. Click the dropdown “GET” and change it to “POST”.
  2. Add the Ethnio OAuth API link:
<span style="font-weight: 400;"> </span>https://ethn.io/api/v1/oauth/token
  1. Select “Body” and then check the box for “Raw”.
  2. Then, click the dropdown “TEXT” and change it to “JSON”.
  3. Click send.
  4. Next, copy and paste the text below into the top body (the empty space). 
<span style="font-weight: 400;">{</span><br><br><span style="font-weight: 400;">    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",</span><br><br><span style="font-weight: 400;">    "assertion": "</span><strong>your web token copied from the last step goes here</strong><span style="font-weight: 400;">"</span><br><br><span style="font-weight: 400;">}</span>
  1. Once you have pasted this text, you will need to update the  “assertion” value with the web token you generated earlier (see redacted area on screenshot below).
  2. Click send again to generate your “access_token”, which is used to sign requests and only works for the period of time you defined with your timestamp.

Final view:

Pool Member Delete

To send and authorize the Pool member erasure request follow the steps below.

Authorization: first, you will need to authorize the erasure request.

Open another tab in Postman.

  1. Click the dropdown “GET” and change it to “POST”.
  2. Add the Ethnio delete API link: 
https://ethn.io/api/v1/pool_members/delete
  1. Click “Headers”
  2. From “KEY” type “Authorization” and select it from the list. See screenshot below.
  3. From “VALUE” paste: Bearer .access token from the last step goes here
  4. Once pasted, you will need to update the value with the access_token you generated from the last step.

Body Tab: go back to the body tab and follow the steps below to complete.

  1. Select “Body” and then check the box for “Raw”.
  2. Then, click the dropdown “TEXT” and change it to “JSON”.
  3. Next, copy and paste the text below into the top body (the top space). 

{

  "email": ["some@email.com"]

}

  1. Once you have pasted this text, you will need to update the  “email” value with the email address(s) you want to delete.
  2. Click send to run the delete request.

Final view:

Still need help? Contact Us Contact Us