Best Practices

This guide covers essential best practices for working with the Egnyte Public API, including when to use the Remote MCP Server instead of the REST APIs, authentication, rate limiting, data formatting, and error handling.

Choosing Between MCP and the REST APIs

Egnyte offers two ways to build on your content: the Remote MCP Server and the REST APIs documented on this portal, which you can also call through the Agentic CLI. Both respect the authenticated user's Egnyte permissions and share the same rate limits. They fit different jobs, so pick the one that matches how your integration works.

Use the Remote MCP Server When

The Remote MCP Server is the better fit when a person works with Egnyte content through an LLM client such as Claude, ChatGPT, Microsoft Copilot, or Gemini Enterprise. You connect the client to https://mcp-server.egnyte.com/mcp, the user signs in with OAuth 2.0, and the client discovers the available tools on its own. There is no integration code to write or maintain.

Choose MCP for:

• Questions across content. A user asks Claude to find the latest signed contract for a project and summarize its payment terms. The client chains search, get_file_content, and ask_document without any code from you.
• Egnyte Agents and AI Assistant in the tools people already use. A project team asks one of its Egnyte Agents a question from ChatGPT, using list_agents, ask_agent, and get_agent_ask_status.
• Light, user-driven actions. A user asks the client to create a folder, upload a generated report, add a comment, or create a share link while working in a conversation.
• Prototyping an AI workflow. Try an idea in an MCP client against real content before deciding whether it needs a dedicated integration.

Use the REST APIs When

The REST APIs are the better fit when your code, not a person in a conversation, decides what happens and when. They give you exact control over requests, pagination, retries, and error handling.

Choose the REST APIs for:

• Bulk and scheduled work. Migrating content into Egnyte, applying metadata to thousands of files, or running a nightly job. See the File System API and the Metadata API.
• Large files. The File System API supports chunked upload for files larger than 100 MB. Uploads through the MCP Server are reliable up to about 200 MB.
• Reacting to changes. Keeping an external system in sync with Egnyte through the Events API or Webhooks API.
• Administration. Provisioning users and groups, managing permissions, or acting on behalf of other users with impersonation. See the User Management API and the Permissions API.
• Embedding Egnyte in your own product. Building your own interface, including calling Egnyte AI from your application through the AI API and the Agents API.

Use the Agentic CLI When

The Agentic CLI (@egnyte/agentic-cli) is a command-line tool built on the REST APIs. It is the better fit when an AI coding agent or a script works with Egnyte from a terminal or CI pipeline, and you do not want to write HTTP code.

Choose the Agentic CLI for:

• AI coding agents. Claude Code, Cursor, or Copilot Workspace run Egnyte commands and read the JSON output. The agent can discover operations with egnyte schema --list, and --fields trims responses to reduce token cost.
• Scripts and CI pipelines. Authenticate with the EGNYTE_TOKEN and EGNYTE_DOMAIN environment variables, and run bulk operations from a CSV with --bulk-file-path and --parallelism.
• Reviewing changes before they run. Every command that changes content requires --dry-run, which prints the equivalent curl command, or --yes to run it.

Use Both

Many integrations combine the two. A common pattern is to use the REST APIs to load and organize content, set metadata, and keep it current, and then give users the Remote MCP Server so they can ask questions about that content from their LLM client.

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
• Remote MCP Server: Connect LLM clients to Egnyte content