Best Practices

Using Access Tokens

Once you have an API key, your next step is to use that key to authenticate to get an access token to use for all API requests. Please check the authentication documentation page to see how to authenticate for your type of key and application.

Once you get a token, you must cache it for use in regular API calls rather than making a token request each time you make an API request. Though tokens do not expire, tokens will stop working if a user changes their password.

All API actions are executed within the permission context of the user. You can only access resources (e.g. files or folders) that the user has permissions to access. If you are using an administrative account, you can optionally use a feature called User Impersonation to perform an action on behalf of a user. Impersonated calls are executed in the context of the user being impersonated and are noted in our audit reports as impersonated calls.

Rate Limiting

Our API rate limits restrict both the number of calls per day and number of calls per second. Our API rate limits and daily usage limits are enforced per access token rather than against the entire key. So, even if one user exceeds their quota under your key, other users will still be able to access Egnyte through your application. Integrations should be built with inherent support for receiving and handling these throttles. The default settings for all tokens issued under a key are:

If you anticipate that your API call volume will exceed these limits when your application is in production, please contact us and we can discuss other arrangements.

If your API call is throttled you will see a response with a 403 HTTP status code with one of two possible values for the X-Mashery-Error-Code header field:

The Retry-After header will be set to the number of seconds until the relevant throttle will next be reset.

In addition to the general API endpoint rate limiting, the OAuth token endpoint (/puboauth/token) is also rate limited. For the Publicly Available Application authentication flow, the limit is 100 token requests per hour. For the Internal Application authentication flow, the limit is 10 calls/user/hour. When throttled, you will see a response with a 409 HTTP status code. The Retry-After header will be set to the number of seconds until the throttle will next be reset. In general, you will not encounter this limit since you should be requesting a token only once per user and persisting it rather than requesting a token repeatedly.

Formats

File System Paths in URLs

When you're putting file paths in URLs, the individual elements of folder paths in the URL must be URL encoded. However the intervening forward slashes must not be escaped. For example, this path: /Shared/example?path/$file.txt should be encoded as /Shared/example%3Fpath/%24file.txt. This is particularly important for the file system and permission API endpoints.

Timestamps

Dates and times are in ISO 8601 format. For example, May 27, 2014 is represented as 2014-05-27. Similarly 10:27:01pm on May 27, 2014 is represented as 2014-05-27T22:27:01Z.

Impersonation

Public API allows admin users to impersonate any other user by providing their username or e-mail address associated with the account. To impersonate, you need to make an API call with OAuth token of an admin user and one of the following headers.

You only need one of the headers. If both are provided, X-Egnyte-Act-As-Email will be ignored.

Impersonation Example to Create Folder

POST /pubapi/v1/fs/Shared/test HTTP/1.1
  Host: apidemo.egnyte.com
  Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
  X-Egnyte-Act-As-Email: test@test.com
  Content-Type: application/json

curl -v -X POST -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
        -H "X-Egnyte-Act-As-Email: test@test.com" \ 
        -H "Content-Type: application/json"\
         https://apidemo.egnyte.com/pubapi/v1/fs/Shared/test

Common HTTP Headers

HTTP Request Headers

HTTP Response Headers

Common Response Codes

Error Messages

Errors are returned in the HTTP Status Code of the response. The response body also includes an array of errors that provide a more descriptive description of the error. If multiple errors were found, the API will include multiple entries.

HTTP/1.1 404 NOT FOUND

{"Errors": [{"description": "Link does not exist.","code": "404"}]}