Best Practices

This guide covers essential best practices for working with the Egnyte Public API, including authentication, rate limiting, data formatting, and error handling.

Using Access Tokens

Obtain and Cache Tokens

After obtaining an API key, authenticate to receive an access token for all API requests. See Authentication for details on obtaining tokens for your application type.

Always cache your access token. Do not request a new token for every API call. Tokens expire after 30 days or when the user changes their password.

Permission Context

All API actions execute within the permission context of the authenticated user. You can only access resources (files, folders, etc.) that the user has permission to access.

User Impersonation

Administrators can perform actions on behalf of another user using impersonation. Impersonated calls execute in the context of the impersonated user and are logged as such in audit reports. See Impersonation below for implementation details.

Rate Limiting

Default Limits

Rate limits are enforced per access token, not per API key. If one user exceeds their quota, other users under the same key remain unaffected.

Proactive Rate Limit Monitoring

Monitor rate limit headers in every API response to avoid hitting limits. Parse these headers and implement throttling logic in your application.

Rate Limit Headers

Implementation Strategy

1. Check QPS on each response: If X-Accesstoken-Qps-Current equals or approaches X-Accesstoken-Qps-Allotted, pause for 1 second before the next request.
2. Monitor daily quota: Track X-Accesstoken-Quota-Current to avoid exceeding your daily limit.

OAuth Token Endpoint Rate Limiting

The OAuth token endpoint (/puboauth/token) has separate rate limits:

• Public apps: 100 token requests per hour
• Internal apps: 10 token requests per user per hour

When throttled, you receive a 409 Conflict response with a Retry-After header indicating seconds until the limit resets.

Formats

File System Paths in URLs

When including file paths in URLs, encode each path segment individually. Do not encode forward slashes (/) between segments.

Example:

Original path:

/Shared/example?path/$file.txt

Correctly encoded:

/Shared/example%3Fpath/%24file.txt

This encoding is critical for File System and Permissions API endpoints.

Timestamps

All dates and times use ISO 8601 format.

Examples:

• Date: 2014-05-27
• Date and time: 2014-05-27T22:27:01Z

Impersonation

Administrators can impersonate any user by including one of the following headers in API requests:

X-Egnyte-Act-As: {username}

or

X-Egnyte-Act-As-Email: {email}

Requirements

• The OAuth token must belong to an administrator
• The impersonated user must exist in the domain

Example: Create Folder as Another User

HTTP

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

curl -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"

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v1/fs/Shared/test" \
     -H "X-Egnyte-Act-As-Email: test@test.com" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Common HTTP Headers

Request Headers

Response Headers

Common Response Codes

Error Messages

Errors are returned in the HTTP status code and response body. The response body contains an Errors array with detailed error information. Multiple errors may be included if applicable.

Example Error Response

HTTP/1.1 404 NOT FOUND

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

Related Resources

• Authentication — How to obtain and refresh OAuth tokens
• File System API — Create, read, update, and delete files and folders
• Permissions API — Manage user and group permissions