Egnyte Protect Public API (1.0.0)

Download OpenAPI specification:Download

Egnyte Protect Public API exposes issues for the purpose of listing, polling for new issues and watching for changes in issue pool.

Definitions:

Environment
One of the two egnyteprotect.com subdomains to use with the API: usc1-api.egnyteprotect.com or euw1-api.egnyteprotect.com
Tenant
A company/organization account in Egnyte Protect.
Issue
A violation of data protection policies listed in Protect

Authentication

CodeGrantAuth

Code Grant from OAuth2 is used for obtaining tokens to the API for applications using the Public API to provide functionality for Protect users.

Request a client_id from https://developers.egnyte.com - register and select "Issue a new key for Egnyte Protect" to get it.

Example calls

# get code - open in the browser
https://usc1-api.egnyteprotect.com/oauth2/code?client_id=CLIENT_ID&redirect_uri=https://your-app.com/oauthredirect&response_type=code&scope=issues:read

# exchange code for token - POST request
curl -v -d 'client_id=CLIENT_ID&client_secret=SECRET&grant_type=authorization_code&redirect_uri=https://your-app.com/oauthredirect&code=CODE' https://usc1-api.egnyteprotect.com/oauth2/token

# refresh token - POST request
curl -v -d 'client_id=CLIENT_ID&client_secret=SECRET&grant_type=refresh_token&redirect_uri=https://your-app.com/oauthredirect&refresh_token=REF_TOKEN' https://usc1-api.egnyteprotect.com/oauth2/token
Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://<env>.egnyteprotect.com/oauth2/code
Token URL: https://<env>.egnyteprotect.com/oauth2/token
Refresh URL: https://<env>.egnyteprotect.com/oauth2/token
Scopes:
  • issues:read -

    read issues listings and details

  • classification:write -

    upload items and metadata for classification

Subject Access Request

Create a Subject Access Request

Creates a SAR. IDs in "identifiers" come from the endpoint for listing identifiers

Authorizations:
CodeGrantAuth (sar:write)
Request Body schema: application/json
required
object
requestType
required
string (SARRequestType)
Enum: "NOTIFICATION" "RIGHT_TO_BE_FORGOTTEN"
serviceTime
number

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "c9ac0519-284a-4bee-9574-30ae7891e5dc"
}

Get SAR

Returns SAR details, including status and stage of processing the SAR.

Authorizations:
CodeGrantAuth (sar:readsar:write)
path Parameters
sarId
required
string <uuid> (SARId)

Id of the SAR

Responses

Response samples

Content type
application/json
Example
{
  • "id": "096e400e-56db-4128-bdea-05ebcea9ab7e",
  • "subject": {
    },
  • "requestType": "NOTIFICATION",
  • "stage": "COLLECTING_DATA",
  • "daysLeft": 29,
  • "created": 1576580243855,
  • "serviceTime": 30,
  • "servicedDays": 0,
  • "serviceDate": 1576580243855,
  • "processed": false,
  • "completed": false,
  • "actions": {}
}

List paths from fulfilled SAR

Returns paths to files from SAR matches

Authorizations:
CodeGrantAuth (sar:readsar:write)
path Parameters
sarId
required
string <uuid> (SARId)

Id of the SAR

query Parameters
count
integer [ 1 .. 100 ]
Default: 100

Number of items to return at most

cursor
string

cursor value from the previous response body - for continuity. Each response is returning a cursor - a string pointing to the place on the list of files from SAR matches, and each request passes the last known cursor value to get items which occurred after that. null in the response means that pagination is over

Responses

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "cursor": "string"
}

Delete SAR files

Authorizations:
CodeGrantAuth (sar:write)
path Parameters
sarId
required
string <uuid> (SARId)

Id of the SAR

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": "string"
}

Classification Source

Register a source for classification

Creates a classification source in Protect sourceId in response can be used to unregister, it also shows up as sourceId in results of Content Classification and Issues

Authorizations:
CodeGrantAuth (classification:write)
Request Body schema: application/json
transport
required
string
Value: "https"

Transport choice. https is the default, more will be added.

discoveryURL
required
string

URL of the Classification FS discovery endpoint for the particular source.

sourceDisplayName
required
string

Visible name of the registered source.

location
string

Visible name of the location of the source, can be left empty or used as a hint to the user as to where to look for the source (a network address or a specific section of the source system).

troubleshootingURL
required
string

A URL to display to the user if the classification source stops responding. Can be a direct link to configuration of the source or a link to a troubleshooting guide.

authHeader
string

The content for authorization header of requests made to Classification FS.

emailContact
string

E-mail address to contact when source is down for.

sourceType
string

Display name of source.

iconUrl
string

Source icon url.

Responses

Request samples

Content type
application/json
{
  • "transport": "https",
  • "discoveryURL": "string",
  • "sourceDisplayName": "string",
  • "location": "string",
  • "troubleshootingURL": "string",
  • "authHeader": "string",
  • "emailContact": "string",
  • "sourceType": "string",
  • "iconUrl": "string"
}

Response samples

Content type
application/json
{
  • "sourceId": "string"
}

Unregister classification source

Unregister a classification source from Protect

Authorizations:
CodeGrantAuth (classification:write)
path Parameters
sourceId
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": "string"
}

Request a test run on a classification source

Runs a simulation of a Classification Source scan pass on the given source URL and invokes report endpoint with issues it finds.
Does not return a success/failure result - it's intended as a tool for helping the developer during work and manual acceptance testing, not as a CI/CD tool.

Authorizations:
CodeGrantAuth (classification:write)
Request Body schema: application/json
transport
required
string
Value: "https"

Transport choice. https is the default, more will be added.

discoveryURL
required
string

URL of the Classification FS discovery endpoint for the particular source

authHeader
string

The content for authorization header of requests made to Classification FS

Responses

Request samples

Content type
application/json
{
  • "transport": "https",
  • "discoveryURL": "string",
  • "authHeader": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": "string"
}

Sensitive Content

Get policies

Returns policies from current tenant's setup.
Content listing will only refer to policies by tags. Details and display names can be resolved from this endpoint.
Policies don't change often so it's reasonable to cache the response to this.

Authorizations:
CodeGrantAuth (sc:read)

Responses

Response samples

Content type
application/json
No sample

Get sources

Lists all sources installed for the tenant. IDs are useful for exploring sensitive content in selected ones.

Authorizations:
CodeGrantAuth (sc:read)

Responses

Response samples

Content type
application/json
No sample

Locations

List locations with Sensitive Content found. Returns a list of paths to locations containing files identified as sensitive.

Authorizations:
CodeGrantAuth (sc:read)
path Parameters
sourceId
required
string (SourceId)

ID of the source

query Parameters
cursor
string

The cursor returned in previous request

count
number [ 1 .. 100 ]

The number of items to return in one response

Responses

Response samples

Content type
application/json
No sample

Get location

Get location details along with the list of IDs of sensitive files found.

Authorizations:
CodeGrantAuth (sc:read)
path Parameters
sourceId
required
string (SourceId)

ID of the source

locationId
required
string <uuid> (SCLocationId)

ID of the location to read

Responses

Response samples

Content type
application/json
No sample

List location

List files in a location.

Authorizations:
CodeGrantAuth (sc:read)
path Parameters
sourceId
required
string (SourceId)

ID of the source

locationId
required
string <uuid> (SCLocationId)

ID of the location to list

query Parameters
cursor
string

The cursor returned in previous request

count
number [ 1 .. 100 ]

The number of items to return in one response

Responses

Response samples

Content type
application/json
No sample

Get file

Get sensitive file details.

Authorizations:
CodeGrantAuth (sc:read)
path Parameters
sourceId
required
string (SourceId)

ID of the source

fileId
required
string <uuid> (SCFileId)

ID of the file to read

query Parameters
classificationStatus
boolean (SCIncludeClassificationStatus)

Option to get status of classification

Responses

Response samples

Content type
application/json
No sample

Get matches

Get sensitive file details including the list of matched content occurrences. > Note a specific scope is required for this endpoint access

Authorizations:
CodeGrantAuth (sc:matches)
path Parameters
sourceId
required
string (SourceId)

ID of the source

fileId
required
string <uuid> (SCFileId)

ID of the file to read

query Parameters
includeTextContext
number [ 10 .. 250 ]

Number of characters before and after the match to include in the context. Context is only returned if this parameter is set. Otherwise context field is missing from response.

Responses

Response samples

Content type
application/json
No sample

Get classification status

Get status of file's classification

Authorizations:
CodeGrantAuth (sc:read)
path Parameters
sourceId
required
string (SourceId)

ID of the source

query Parameters
versionId
required
string <uuid> (SCFileVersionId)

ID of the version of the file to read

Responses

Response samples

Content type
application/json
No sample

Issues

Get list of issues

Returns Protect issues, starting from oldest, uses a cursor to iterate without duplicates.

Issue
A violation of data protection policies listed in Protect
Cursor
A value pointing to a location in the list of issues. Cursor refers to the last item you already received. The API will return items newer than the cursor.

Authorizations:
CodeGrantAuth (issues:read)
query Parameters
count
integer [ 1 .. 100 ]
Default: 100

Number of items to return at most

cursor
integer <int64> (IssueId) >= 0

Most recent known id, return items with IDs after this one.

Responses

Response samples

Content type
application/json
{
  • "cursor": 46,
  • "issues": [
    ]
}

Get cursor

Get latest cursor or a cursor for provided timestamp. Returns cursor (issue id) for timestamp specified as startTime param. When querying issue listing for the cursor provided, you'll receive all issues created on the timestamp or later.
If the timestamp is older than the oldest issue, the API returns a cursor pointing to a value before all issues
If the timestamp is newer than the newest issue or not provided at all, a cursor is returned that, when used, will only return future issues. (useful for polling for new issues)

Authorizations:
CodeGrantAuth (issues:read)
query Parameters
startTime
integer >= 1500000000000

Timestamp in miliseconds for which to get the cursor

Responses

Response samples

Content type
application/json
{
  • "cursor": 2343
}

Get list of issues updates

Returns Issues in their current state, but ordered by their modification time. Polling this endpoint starting at the current timestamp will result in getting a list of issues as they're being updated or added. Polling with no timestamp to start with will list all issues in their current state and continue returning issues as they're being added or changed over time. Responses from this endpoint may contain more elements than the declared count if the last item in the returned set was not the last with the same timestamp value.

Authorizations:
CodeGrantAuth (issues:read)
query Parameters
count
integer [ 1 .. 100 ]
Default: 100

Approximate number of items to return. API doesn't not guarantee the exact match.

modifiedAfter
integer <int64> (TimestampMs) >= 0

Most recent known timestamp, return items which were updated after that timestamp.

Responses

Response samples

Content type
application/json
{
  • "modifiedAfter": 0,
  • "issues": [
    ]
}

Get issue details

Returns detailed information about selected issue. It allows to track its status over time.

Authorizations:
CodeGrantAuth (issues:read)
path Parameters
id
required
integer <int64> (IssueId) >= 0

ID of the issue to return

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "sourceId": "string",
  • "status": "string",
  • "type": "string",
  • "source": "string",
  • "sourceLabel": "string",
  • "sourceType": "string",
  • "severity": 1,
  • "updated": 0,
  • "detected": 0,
  • "item": {
    },
  • "policies": [
    ]
}

Issues Webhooks

Register an issues webhook

Allows for webhook registration. It will be getting notifications about changes in Egnyte Protect issues. Endpoint returns ID of newly registered webhook, expiration timestamp and current status.

Authorizations:
CodeGrantAuth (issues:read)
Request Body schema: application/json
url
required
string
eventType
Array of strings (EventType) non-empty
Items Enum: "create" "modify" "resolve"
authHeader
string

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "webhookId": "c9ac0519-284a-4bee-9574-30ae7891e5dc",
  • "expires": 2100000000,
  • "status": "enabled"
}

Get users webhooks

Returns webhooks ID, expiration timestamp and status.

Authorizations:
CodeGrantAuth (issues:read)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Unregister an issues webhook

Allows for webhook unregistration.

Authorizations:
CodeGrantAuth (issues:read)
path Parameters
webhookId
required
string (WebhookId)

ID of the webhook to unregister

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": "string"
}

Get webhook status

Returns webhook ID, expiration timestamp and status.

Authorizations:
CodeGrantAuth (issues:read)
path Parameters
webhookId
required
string (WebhookId)

ID of the webhook

Responses

Response samples

Content type
application/json
Example
{
  • "webhookId": "c9ac0519-284a-4bee-9574-30ae7891e5dc",
  • "expires": 2100000000,
  • "status": "enabled"
}

Set webhook status

Allows to set webhook status.

Authorizations:
CodeGrantAuth (issues:read)
path Parameters
webhookId
required
string (WebhookId)

ID of the webhook

Request Body schema: application/json
status
required
string
Enum: "enabled" "disabled"

Responses

Request samples

Content type
application/json
Example
{
  • "status": "enabled"
}

Response samples

Content type
application/json
Example
{
  • "webhookId": "c9ac0519-284a-4bee-9574-30ae7891e5dc",
  • "expires": 2100000000,
  • "status": "enabled"
}

Legal Hold

Create Legal Hold

A Legal Hold retains content related to a legal matter, securing all files defined in the hold scope that were created, accessed or deleted within a specified date range. These files will be retained until the Legal Hold is closed or cancelled.
Criteria for hold scope are defined in this request, but can be modified and extended later

Authorizations:
CodeGrantAuth (legalhold:write)
Request Body schema: application/json
name
required
string non-empty

Human-readable name of the Legal Hold.

description
string

Description of the particular Legal Hold.

legalMatter
required
string non-empty

Legal matter concerning this particular Legal Hold.

startDate
integer <int64> >= 0

Unix timestamp.

endDate
integer <int64> >= 0

Unix timestamp.

holdScopeOperator
required
string
Enum: "or" "and"

Logical operator defining if ANY or ALL hold scope's criteria should apply to the file for it to be retained.

required
object

Hold scope's criteria.

Responses

Request samples

Content type
application/json
{
  • "name": "Copyright Infringement Claim",
  • "description": "Claims of Copyright Infringement by Competitor",
  • "legalMatter": "Copyright Infringement",
  • "startDate": 1566370800000,
  • "endDate": 1575435600000,
  • "holdScopeOperator": "or",
  • "holdScope": {
    }
}

Response samples

Content type
application/json
{
  • "legalHoldId": "df497868-9f1b-4ef2-963c-436d9156a91e"
}

Get list of Legal Holds

Returns Legal Holds. The list can be filtered by status.

Authorizations:
CodeGrantAuth (legalhold:read)
query Parameters
status
string (LegalHoldStatus)
Enum: "open" "closed"

Legal Holds status used for filtering. If not provided, all Legal Holds will be returned.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Legal Hold details

Returns details of the Legal Hold. This includes the fields defined when creating it and also current status.

Authorizations:
CodeGrantAuth (legalhold:read)
path Parameters
legalHoldId
required
string <uuid>

ID of the Legal Hold

Responses

Response samples

Content type
application/json
{
  • "name": "Copyright Infringement Claim",
  • "description": "Claims of Copyright Infringement by Competitor",
  • "legalMatter": "Copyright Infringement",
  • "startDate": 1566370800000,
  • "endDate": 1575435600000,
  • "holdScopeOperator": "or",
  • "holdScope": {
    },
  • "status": "open",
  • "createdBy": "Bob Green",
  • "createdDate": 1576535600000,
  • "lastModified": 1576535600000,
  • "userFacingId": "LH00001"
}

Update Legal Hold settings

Only settings that were provided in the request will be updated. The rest won't be changed. Regarding hold scope's criteria this endpoint will overwrite only those that were passed.
It means that if there are only 'folders' defined in the request under 'holdScope', the list of custodians won't be updated.
To clear the list of folders or custodians in the hold scope, empty array '[]' should be passed.

Authorizations:
CodeGrantAuth (legalhold:write)
path Parameters
legalHoldId
required
string <uuid>

ID of the Legal Hold

Request Body schema: application/json
name
string non-empty

Human-readable name of the Legal Hold.

description
string

Description of the particular Legal Hold.

legalMatter
string non-empty

Legal matter concerning this particular Legal Hold.

startDate
integer <int64> >= 0

Unix timestamp.

endDate
integer <int64> >= 0

Unix timestamp.

holdScopeOperator
string
Enum: "or" "and"

Logical operator defining if ANY or ALL hold scope's criteria should apply to the file for it to be retained.

object

Hold scope's criteria.

Responses

Request samples

Content type
application/json
{
  • "name": "Copyright Infringement Claim",
  • "description": "Claims of Copyright Infringement by Competitor",
  • "legalMatter": "Copyright Infringement",
  • "startDate": 1566370800000,
  • "endDate": 1575435600000,
  • "holdScopeOperator": "or",
  • "holdScope": {
    }
}

Response samples

Content type
application/json
""

Delete Legal Hold

Deletes Legal Hold definition from the system. This action is not recoverable and nothing is retained. The corect way to end working with a Legal Hold is to close it - see the /close endpoint.

Authorizations:
CodeGrantAuth (legalhold:write)
path Parameters
legalHoldId
required
string <uuid>

ID of the Legal Hold

Responses

Response samples

Content type
application/json
""

Close Legal Hold

Files retained for this Legal Hold will no longer be preserved.
Closing Legal Hold doesn't remove it entirely from the system. It's still possible to check some of the Legal Hold details.

Authorizations:
CodeGrantAuth (legalhold:write)
path Parameters
legalHoldId
required
string <uuid>

ID of the Legal Hold

Responses

Response samples

Content type
application/json
""

Modify hold scope

Hold scope's criteria, folders and custodians, can be modified by adding or deleting items which expand or shrink the hold scope.

Authorizations:
CodeGrantAuth (legalhold:write)
path Parameters
legalHoldId
required
string <uuid>

ID of the Legal Hold

Request Body schema: application/json
object

Definition of items to be added to the hold scope. If the content of the particular folder ids list shouldn't be changed, empty array should be passed.

object

Definition of items to be deleted from the hold scope. If the content of the particular folder ids list shouldn't be changed, empty array should be passed.

Responses

Request samples

Content type
application/json
{
  • "add": {
    },
  • "delete": {
    }
}

Response samples

Content type
application/json
""

Get retained files

Returns retained files matching Legal Hold settings. Resulting items are paginated using a cursor. Pagination may return pages with less items than expected based on permissions to view them. As long as a cursor is not null, there's more data to fetch

Authorizations:
CodeGrantAuth (legalhold:read)
path Parameters
legalHoldId
required
string <uuid>

ID of the Legal Hold

query Parameters
cursor
string

The cursor returned in the previous request.

count
integer [ 1 .. 100 ]
Default: 100

Number of items to return in one response.

Responses

Response samples

Content type
application/json
{
  • "cursor": null,
  • "files": [
    ]
}

Dev Tools

Get basic information about the user

Returns information about the user making request: data from Protect plus clientId of application used.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "clientId": "hweb8adyh3gumiypa45qdgkm",
  • "user": "d870600d-dd67-448f-b482-7c4618862008",
  • "tenant": "fc7e9d03-b838-40b3-ae6b-80f761f418d7",
  • "scopes": [
    ]
}

Request a test run on a classification source

Runs a simulation of a Classification Source scan pass on the given source URL and invokes report endpoint with issues it finds.
Does not return a success/failure result - it's intended as a tool for helping the developer during work and manual acceptance testing, not as a CI/CD tool.

Authorizations:
CodeGrantAuth (classification:write)
Request Body schema: application/json
transport
required
string
Value: "https"

Transport choice. https is the default, more will be added.

discoveryURL
required
string

URL of the Classification FS discovery endpoint for the particular source

authHeader
string

The content for authorization header of requests made to Classification FS

Responses

Request samples

Content type
application/json
{
  • "transport": "https",
  • "discoveryURL": "string",
  • "authHeader": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "details": "string"
}