Protect API

The Egnyte Protect Public API lets you create applications that securely interact with Egnyte Protect in the following ways:

  • Pull Issues from Egnyte
  • Ingest data for Classification

 

Authorization

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.

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

 

Issues API

This endpoint is used to pull Egnyte Protect Issues from the domain.

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.

 

GET /v1/issues
AUTHORIZATIONS:
CodeGrantAuth (issues:read)

Request Parameters

ParameterDescriptionRequiredPossible Values
count Number of items to return at most (Default: 100)  No integer [1 ... 100]
cursor Most recent known id, return items with IDs after this one Yes integer <int64> (IssueId) >= 0

Responses

Expected Response

The response is a HTTP 200 OK Code with a list of issues returned with a cursor for the next request

Sample Response

{
    "cursor": 46,
    "issues": [
    {
        "id": 1,
        "sourceId": "1232f6b8-3258-4528-ab64-b4a636da3327",
        "status": "OPEN",
        "type": "INDIVIDUAL_PERMISSION",
        "source": "someworkgroup.egnyte.com",
        "sourceLabel": "Source added by tests",
        "sourceType": "Egnyte",
        "severity": 1,
        "item": {
            "type": "FOLDER",
            "displayName": "/Shared/2018-09-04_10-37-02/folder-parent14/folder15"
        },
        "updated": 1536050328021,
        "detected": 1536050328021,
        "policies": [ ]
    },
    {
        "id": 2,
        "sourceId": "1232f6b8-3258-4528-ab64-b4a636da3327",
        "status": "OPEN",
        "type": "PUBLIC_LINK",
        "source": "someworkgroup.egnyte.com",
        "sourceLabel": "Source added by tests",
        "sourceType": "Egnyte",
        "severity": 2,
        "item": {
            "type": "FILE",
            "displayName": "/Shared/2018-09-04_10-37-02/file6.test"
        },
        "updated": 1536050328571,
        "detected": 1536050328571,
        "policies": [
            "relevant policy name"
        ]
    },
    {
        "id": 46,
        "sourceId": "1232f6b8-3258-4528-ab64-b4a636da3327",
        "status": "OPEN",
        "type": "MALWARE_INFECTION",
        "source": "someworkgroup.egnyte.com",
        "sourceLabel": "Source added by tests",
        "sourceType": "Egnyte",
        "severity": 9,
        "item": {
            "type": "USER",
            "displayName": "Delphi Admin (bob@egnyte.com)"
        },
        "updated": 1536050367669,
        "detected": 1536050367669,
        "policies": [
            "relevant policy name"
        ]
     }
     ]
}

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)

GET /v1/issues/cursor
AUTHORIZATIONS:
CodeGrantAuth (issues:read)

Request Parameters

ParameterDescriptionRequiredPossible Values
startTime Timestamp in milliseconds for which to get the cursor Yes integer >=1500000000000

Expected Response

The response is a HTTP 200 OK Code with a list of issues returned with a cursor for the next request

Sample Response

{
    "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.

GET /v1/issuesupdate
AUTHORIZATIONS:
CodeGrantAuth (issues:read)
Request Parameters
ParameterDescriptionRequiredPossible Values
count Approximate number of items to return. API doesn't guarantee the exact match No integer [1 ... 100]
modifiedAfter Most recent known timestamp, return items which were updated after that timestamp Yes integer <int64> (Timestamp) >= 0

Expected Response

The response is a HTTP 200 OK Code with a list of issues returned with a cursor for the next request

Sample Response

{
    "modifiedAfter": 0,
    "issues": [
    {
        "id": 0,
        "sourceId": "string",
        "status": "string",
        "type": "string",
        "source": "string",
        "sourceLabel": "string",
        "sourceType": "string",
        "severity": 1,
        "updated": 1500000000000,
        "detected": 1500000000000,
        "item": {
            "type": "string",
            "displayName": "string"
        },
        "policies": [ ]
    }
    ]
}

Get detailed information about specified issue

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

 

GET /v1/issues

 

AUTHORIZATIONS:
CodeGrantAuth (issues:read)

Request Parameters

ParameterDescriptionRequiredPossible Values
id ID of the issue to return Yes integer <int64> (IssueId) >=0

Expected Response

The response is a HTTP 200 OK Code with a detailed information about the issue

Sample Response

{
    "id": 0,
    "sourceId": "string",
    "status": "string",
    "type": "string",
    "source": "string",
    "sourceLabel": "string",
    "sourceType": "string",
    "severity": 1,
    "updated": 1500000000000,
    "detected": 1500000000000,
    "item": {
        "type": "string"
    },
    "policies": [
        "string"
    ]
}

 

 

Classification API

This endpoint is used to the details for a specific comment.

Register a source for classification

Creates a classification source in Protect

POST /v1/classification
AUTHORIZATIONS:
CodeGrantAuth (classification:write)

Request Parameters: schema application/json
ParameterDescriptionRequiredPossible Values
transport Transport choice https is default now, more will be added later Yes string = https (only now)
discoveryURL URL of the classification FS discovery endpoint for the particular source Yes string
sourceDisplayName Visible name of the registered source Yes string
location 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) No string
troubleshootingURL A URL to display to the user if the classificatio source stops responding. Can be a direct link to the configuration of the source or a link to a troublshooting guide Yes string
authHeader The content for authorization header of requests made to the Classification FS No string
emailContact Email address to contact when source is down No string

Expected Response

The response is a HTTP 201 OK Code with the sourceId

Sample Response

{
    "sourceId": "string"
}

Unregister classification source

Unregister a classification source from Protect

 

DEL /v1/classificaiton/{sourceId}

 

AUTHORIZATIONS:
CodeGrantAuth (classification:write)

Request Parameters
ParameterDescriptionRequiredPossible Values
sourceId ID of the source Yes string

Expected Response

The response is a HTTP 204 OK Code Source Unregisterd

Sample Response

{
    "code": "string",
    "message": "string",
    "details": "string"
}

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.

 

POST /v1/webhooks/issues

 

AUTHORIZATIONS:
CodeGrantAuth (issues:read)
REQUEST BODY SCHEMA: application/json
 url
required
 string
 eventType
Array of strings (EventType) non-empty
Items Value: "create"
 authHeader
 string
Request Parameters schema: application/json
ParameterDescriptionRequiredPossible Values
url url of the webhook listener Yes string
eventType Array of strings (EventType) non-epty Yes Items value: "create"
authHeader
Yes string

Expected Response

The response is a HTTP 201 OK Code Successfully registered a webhook

Sample Response

{
    "webhookId": "c9ac0519-284a-4bee-9574-30ae7891e5dc",
    "expires": 2100000000,
    "status": "enabled"
}

 

Unregister an issues webhook

Allows for webhook unregistration.

 

DEL /v1/webhooks/issues/{webhookId}
Request Parameters
ParameterDescriptionRequiredPossible Values
webhookid ID of the webhook to unregister Yes string (Webhookid)

Expected Response

The response is a HTTP 204 OK Code Successfully unregistered a webhook

Get webhook status

Returns webhook ID, expiration timestamp and status.

 

GET /v1/webhooks/issues/{webhoookId}/status
Request Parameter
ParameterDescriptionRequiredPossible Values
webhookid ID of the webhook Yes string (Webhookid)

Expected Response

The response is a HTTP 200 OK Code Webhook status information

Sample Response

{
    "webhookId": "c9ac0519-284a-4bee-9574-30ae7891e5dc",
    "expires": 2100000000,
    "status": "enabled"
}

Set webhook status

Allows to set webhook status.

POST /v1/webhooks/issues/{webhookID}/status
Request Parameters
ParameterDescriptionRequiredPossible Values
webhookid ID of the webhookr Yes string (Webhookid)
Request Parameters
ParameterDescriptionRequiredPossible Values
status Status of the webhook Yes string enum: enabled or disabled

Expected Response

The response is a HTTP 200 OK Code updated webhook status information

Sample Response

{
    "webhookId": "c9ac0519-284a-4bee-9574-30ae7891e5dc",
    "expires": 2100000000,
    "status": "enabled"
}