EchoMark Public Rest API - Implementation Guide

The EchoMark Public API allows you to connect your applications, internal tools, or custom document workflows directly to EchoMark. By using the EchoMark Public API, you can build an integration that uploads documents to your existing EchoMark account and tenant and allows for programmatic downloading of marked copies for recipients as needed. Should a leak occur, you can log into your existing EchoMark account and use the EchoMark web application to run leak investigations.

The EchoMark Public API is a REST interface that uses OAuth2 for authorization. In order to call the EchoMark Public API, you will need an EchoMark administrator to create an API client in the EchoMark web application.

API Reference HTML file

Create an API Client

An EchoMark administrator can log into the EchoMark web application and create an API client for use in authorization for the EchoMark Public API by following the steps below.

1. Log into the EchoMark web application
2. Click on Settings, then API Clients

3. Click on the + New client button to create a new client

4. Enter a name for the client, and click on the Create button. The name can be anything that will help you identify it such as “File System Integration” or “My EchoMark Application”.

5. On the next screen, copy the Client ID and Client secret values and save them somewhere. You will not be able to view the Client secret again later, and will need to rotate it to a new one if you lose it. Then, click on the Close button to close the dialog.

Rotate Client Secret

In the case that your client credentials get leaked, or if you would like to rotate through secrets more quickly, you can change your client secret from the EchoMark web application.

1. Log into the EchoMark web application as an administrator.
2. Click on Settings, then select API Clients

3. On the right side of the row with your API Client, click on the … to open the context menu.

4. Click on the Rotate secret menu option. Once you click on the button, your secret will be rotated and the old secret will stop working immediately. Existing access tokens will continue to work, but you will not be able to get new access tokens.

5. Copy the new Client secret and save it somewhere, then click on the Close button to close the dialog. Once you close the dialog box you will not be able to view your secret again.

Rename Client

If you need, you can rename an API Client.

1. Log into the EchoMark web application as an administrator.
2. Click on Settings, then select API Clients

3. On the right side of the row with your API Client, click on the … to open the context menu.

4. Click on the Rename option in the menu

5. Enter in the new name, and click on the Save button.

Delete API Client

In the case that you want to completely remove your API client, you can delete it from the EchoMark web application.

1. Log into the EchoMark web application as an administrator.
2. Click on Settings, then select API Clients

3. On the right side of the row with your API Client, click on the … to open the context menu.

4. Click on the Delete option in the menu.

5. On the confirmation box that pops up, click on the Delete button. This cannot be undone once the client is deleted.

Authorization for the EchoMark Public API

EchoMark uses a Client Credentials OAuth2 flow for authorization to access the EchoMark Public API.

Once you have created your API Client in the EchoMark web application, you can use the Client ID and Client secret to get an access token for authorization for the next API calls. Access tokens last up to 60 minutes before they expire and you need to get a new one.

Getting an Access Token

You can get an access token by encoding your client credentials and then sending a POST request to the EchoMark token endpoint.

1. Base64 encode your Client ID and Client secret combined with a colon:

   EncodedHeader = Base64Encode(<ClientId>:<ClientSecret>)
    

2. Sending the EncodedHeader as a Basic Authorization header in the request, make a POST request to the EchoMark token API endpoint (https://api.echomark.com/auth/oauth2/token) including the following parameters in the POST body as x-www-form-urlencoded values.

   a. grant_type - The type of grant you are requesting. At this time, this should always be client_credentials.

   b. audience - The requested audience. This should be set to **https://api.echomark.com/api**.

   c. resource - The resource you are requesting. This should be set to **https://api.echomark.com/api**.

   d. Sample CURL request:

   curl -X POST <https://api.echomark.com/auth/oauth2/token> \\
   	-H "Authorization: Basic <EncodedHeader>" \\
   	-H "Content-Type: application\\x-www-form-urlencoded" \\
   	-d "grant_type=client_credentials" \\
   	-d "audience=https://api.echomark.com/api" \\
   	-d "resource=https://api.echomark.com/api"
   

   e. You should get the following response which includes the access token:

   {
   	"access_token": "<access_token>"
   	"expires_in": 3600,
   	"expires_at": 123456789,
   	"token_type": "Bearer",
   	"scope": "upload mark"
   }
   

   f. Extract the “access_token” from the JSON object returned to use in calls to the EchoMark API.

Using an access token to authorize an API request

You can use the access_token in the Authorization header of a request to an API by setting the value of the Authorization header to: Bearer <access_token>

Here is an example CURL request using the access token to authorize the API request:

curl -X GET \\
	-H "Accept: application/json" \\
	-H "Authorization: Bearer <access_token>" \\
	<https://api.echomark.com/v1/upload-url>

If the API token is invalid, or has expired, calls to the EchoMark Public API using that token will return a 401 - Unauthorized response instead of a successful response.

EchoMark Public API Rate Limits

EchoMark Public APIs have a specific rate limit set. If you exceed the allowed number of requests per second, you will receive a 429 - Rate Exceeded response instead of a successful response. In that case, please wait a few seconds and try the request again. If you need an increase in your rate limit, contact EchoMark support to see about getting an increase.