Due to a routing related change, some calls to the egnyte.com domain were failing and caused Desktop Sync 'network connectivity' errors. We immediately updated the configuration to rectify the issue. This was only on the 9th of March. Since this has been a persistent issue, I would suggest you file a support ticket with the Egnyte Support team. Mar 02, 2020. Egnyte transforms business through smarter content allowing organizations to connect, protect, and unlock value from all their content. Follow Egnyte on Twitter.
- Previous:Getting Started
- Up:Overview
- Next:File System API
Before you begin making API calls, you must first authenticate to obtain a valid access token to use in subsequent requests. Our APIs use the OAuth 2.0 standard for authentication. We support the Resource Owner, Authorization Code, and Implicit Grant flows. We also support an Enhanced Authentication Service for the Authorization Code flow. Regardless of which flow you use, your application must cache the tokens received rather than making repeated requests for a token.
- If you registered for an internal application key, please refer to the Internal Applications section below.
- If you registered for a publicly available application key, please refer to the Authorization Code or Implicit Grant flows.
- If you registered for the wrong type of key or need to change your domain association, please contact api-support@egnyte.com and we will be happy to help you fix it.
Subsequent Requests
Once you have an OAuth token, all subsequent API calls that you make on a given user's behalf must have the token specified in the header of the request. Set the “Authorization” field to “Bearer <Token>”. For example:
You should persist the OAuth token in your application, rather than making repeated calls to obtain a token for the same user. Treat the token with the same degree of care that you would a saved password.
Bearer tokens issued by Egnyte's APIs do not expire. However, if a user changes their password or explicitly revokes access, then a new token will be required. Therefore, your app must be able to deal with 401 authentication failure scenarios.
Public Applications
If you are an Egnyte partner developing an application for use by our customers, you can use either the Authorization Code flow or Implicit Grant flow to generate an OAuth access token. The Authorization flow is a general-purpose and secure way of getting tokens that are stored in the backend. The Implicit Grant flow is only useful when working in the browser and displays the token to the user. Please note, until you application has been approved for production use, it will only work on the domain registered in your application key's profile.
Authorization Code Flow
The authorization code flow is most commonly used by applications that make server side requests. The token is stored securely in the backend and never shown in the browser.
This is a three stage flow:
1. Initiate the Authentication Flow
Direct the user to the Egnyte OAuth 2.0 login screen using a request like this:
| Variable | Description | Required |
|---|---|---|
| Egnyte Domain | This is the user's Egnyte domain. You will need to prompt the user for the domain name. An example domain name is 'acme'. Note that initially your API key will only work with the single Egnyte domain you told us you would use for testing. When we approve your completed app, we will issue you a new key that works with any Egnyte domain. | Yes |
| client_id | This is the API key that was provided to you when you registered your application. | Yes |
| redirect_uri | This is the URL that we will redirect to after the user has allowed or denied your request to access their account. This must be an HTTPS URL and must match the callback URL configured for your key. E.g. 'https://yourapp.com/oauth' | Yes |
| response_type | This must be set to 'code' for this flow. | Yes |
| scope | Although this parameter is optional from a technical standpoint, all third party applications must scope token requests to only the endpoints they need. We will not approve applications for production use unless they properly scope their token requests or demonstrate a valid need for global scope. More details on OAuth Scopes are provided below. | No |
| state | As described in the OAuth 2.0 spec, this optional parameter is an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter can be used for preventing cross-site request forgery and passing the Egnyte domain as part of the response from the authorization server. | No |
For example:
The user will be taken to an authorization page that asks them to explicitly permit your app to access their Egnyte account. This page displays information about your application taken from your profile. The user must provide their login credentials on this page to authorize your application.
2. Handle the Response from Egnyte
If the user allows your app to access their account, we redirect to:
If the user denies your app, we redirect to:
3. Exchange the code for a token
Make a request to exchange the code for a token by sending an HTTP POST to:
with the following form encoded ('application/x-www-form-urlencoded' format) request body:
| Variable | Description | Required |
|---|---|---|
| Egnyte Domain | This is the user's Egnyte domain. You will need to prompt the user for the domain name. An example domain name is 'acme'. Note that initially your API key will only work with the single Egnyte domain you told us you would use for testing. When we approve your completed app, we will issue you a new key that works with any Egnyte domain. | Yes |
| client_id | This is the API key that was provided to you when you registered your application. | Yes |
| client_secret | This is the secret key that was provided with your key to you when you registered your application. If your application key was requested prior to January 2015, please register for a new key to get one with a client secret. | Yes |
| redirect_uri | This is the callback URL configured for your key. It must be the same as you used in the initial call to the authorization server. | Yes |
| code | The authorization code received from the authorization server in step 2. | Yes |
| grant_type | This must be set to 'authorization_code' for this request. | Yes |
For example, you send a POST to:
With body:
Sample Response Body
Please save this access token and use it when making API requests for this user. Store it encrypted and don't leave it in browser's localStorage.
Enhanced Authentication Service
URLs
Services are available in two regions, Europe and the United States.
OAuth Flow Proxy
This OAuth flow enhances the Authorization Code Flow. The OAuth Flow Proxy does not require knowing the user's Egnyte domain before initiating the flow. The user will be prompted to provide a domain name in the first step of the flow.
Start the Code Auth Flow Proxy using a request in this format:
The end of this flow redirects to the clientUri with an authorization code that should be exchanged for the access token by the client. The domain chosen is available in the Referrer header.
Skipping Domain Choice
If you already know the domain but need to go through the OAuth flow for the user again, you can skip asking for the domain name again.
To skip the first step, add the domain query parameter to the initial Url. The Url can be either the full Url with
Example Initialization of Enhanced OAuth Flow
Initial Call:
The above call will redirect to:
The Egnyte domain name can be retrieved from the Referer header in the final redirect.
Implicit Grant Flow
The implicit grant flow is most commonly used by browser applications. If you want to store access tokens in your back-end, we recommend Authorization Code flow.
This is a two stage flow:
Initiate the Authentication Flow
| Variable | Description | Required |
|---|---|---|
| Egnyte Domain | This is the user's Egnyte domain. You will need to prompt the user for the domain name. An example domain name is 'acme'. Note that initially your API key will only work with the single Egnyte domain you told us you would use for testing. When we approve your completed app, we will issue you a new key that works with any Egnyte domain. | Yes |
| API Key | This is the key string that was provided to you when you registered your application. | Yes |
| redirect_uri | This is the URL that we will redirect to after the user has allowed or denied your request to access their account. This must be an HTTPS URL and must match the callback URL configured for your key. E.g. 'https://yourapp.com/oauth' | Yes |
| response_type | This must be set to 'token' for this flow. | Yes |
| state | As described in the OAuth 2.0 spec, this optional parameter is an opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter can be used for preventing cross-site request forgery and passing the Egnyte domain as part of the response from the authorization server. | No |
| scope | Although this parameter is optional from a technical standpoint, all third party applications must scope token requests to only the endpoints they need. We will not approve applications for production use unless they properly scope their token requests or demonstrate a valid need for global scope. More details on OAuth Scopes are provided below. | No |
For example:
The user will be taken to an authorization page that asks them to explicitly permit your app to access their Egnyte account. This page displays information about your application taken from your profile. The user must provide their login credentials on this page to authorize your application.
2. Handle the Response from Egnyte
If the user allows your app to access their account, we redirect to:
If the user denies your app, we redirect to:
Sample Response Body
Please save this access token and use it when making API requests for this user. Store it encrypted and don't leave it in browser's localStorage.
Internal Applications
Resource Owner Password Credentials Flow
If you are an Egnyte customer developing an application for internal use, you should use the following steps to generate an OAuth token that you will use for all subsequent API calls. These steps correspond to the OAuth 2.0 Resource Owner flow.
Sending the Authentication Request
With the following form-encoded parameters ('application/x-www-form-urlencoded' format) in the request body:
| Variable | Description | Required |
|---|---|---|
| client_id | This is the key string that was provided to you when you registered your application. E.g. 'cba97f3apst9eqzdr5hskggx'. | Yes |
| client_secret | This is the secret key that was provided with your key to you when you registered your application. E.g. '8WkD6YhXJDZrV7kWABQtr2bXBUY5GRTmuqBpRs4JDWHkNNhSK9'. If your application key was requested prior to January 2015, please register for a new key to get one with a client secret. | Yes (if your application key was requested after January 2015 and has a secret) |
| username | This is the Egnyte username of the user on whose behalf you are acting. | Yes |
| password | This is the Egnyte password of the user. | Yes |
| grant_type | This must always be set to 'password' | Yes |
| scope | Space delimited list of OAuth Scopes | No |
Request Examples
Sample Response Body
Please save this access token and use it when making API requests for this user. Please note, this token does not expire until the user's password is changed.
Error Codes
| Error Code | Error Message | HTTP Code | Troubleshooting |
|---|---|---|---|
| APIKEY_FOR_IMPLICIT | This API key is configured only for Implicit Grant flow. Please check the documentation and try again. | 400 | Your key is configured to work with the Implicit Grant flow. If you are an Egnyte customer developing an application for internal use, please contact api-support@egnyte.com and we will be happy to convert your key. Otherwise, please follow the instructions for using the Implicit Grant flow. |
| INTERNAL_ERROR | Oauth request from this source has gone over its rate limit quota. | 400 | For some reason, your application is repeatedly making requests to the authorization endpoint for the same user. Please check your application logic to ensure tokens are being properly cached. |
| INTERNAL_ERROR | No active developer profile found for api key | 401 | Your API key is invalid. Please confirm your API key is correct and is being sent properly in the request. |
| INTERNAL_ERROR | null | 400 | Check the parameters you are sending. There is a good chance you have an invalid parameter name or a syntax error. |
| INVALID_USERNAME_OR_PASSWORD | Invalid client credentials were supplied. | 403 | Please make sure that a) the username and password are correct; b) that you have provided client_secret in the request. Also, c) some HTTP libraries have trouble with special characters. If your credentials are correct but you are still having trouble, you might test your library with a simpler password to see if your library is causing the issue. |
| GRANT_PASSWORD | For resource owner flow, grant_type must be password. Check documentation and try again. | 403 | Make sure you have set the grant_type parameter to 'password' and try again. |
| RESOURCE_FLOW_ISNULL | Resource owner flow based access request but username and/or password is null. Please check documentation and try again. | 400 | If you are receiving a secondary message about an invalid username or password, you probably did not add a username or password in the reqeust body. If you are just seeing the message above in the response body, you are probably missing the Content-Type header or have an invalid header. |
OAuth Scopes
By default, any OAuth token you create will be permitted to access all available Egnyte APIs. You should restrict a given token to a subset of APIs by passing the scope parameter in the token request call. For example, in order to restrict a token to only be able to call the File System API, pass the parameter ”scope=Egnyte.filesystem”. For the Authorization Code and Implicit Grant flows, you pass the scope parameter in the query string. For the Resource Owner Password Credentials flow you pass it along with the other form-encoded parameters in the request body.
The list of currently supported scopes:
| Scope Identifier | API |
|---|---|
| Egnyte.filesystem | File System, Search, Comments, Events, Folder Options, User Insights, Trash |
| Egnyte.user | User Management |
| Egnyte.group | Group Management |
| Egnyte.audit | Audit Reporting |
| Egnyte.link | Links |
| Egnyte.permission | Permissions |
| Egnyte.salesforce | Other Applications -> Salesforce |
| Egnyte.bookmark | Bookmarks |
| Egnyte.launchwebsession | Embedded UI |
If you specify more than one scope, they must be space-delimited. E.g. “scope=Egnyte.filesystem Egnyte.link”. OAuth tokens created through the Publicly Available Applications flow will present all requested scopes to the end user. For instance if you do not request a specific scope, then the user will be shown the following text in the authorization dialog:
This application will be able to:
Egnyte Mac Failed Download Error Failed
- Read, write and delete files/folders
- Create, update and delete users
- Generate audit reports
- Create and delete file/folder links
- Add, update, delete and report on folder permissions
Requesting access to only the APIs your application strictly needs will increase the chance that an end user will grant permission. Avoid requesting scopes that your application does not actually need.
Getting User Info for an OAuth Token
To obtain user info for a given OAuth token, you make a GET request to the following URL (using OAuth authorization):
Request Examples
Sample Response Body
Revoking an OAuth Token
Call this API to revoke access to an OAuth access token
With the following form-encoded parameters ('application/x-www-form-urlencoded' format) in the request body:
| Variable | Description | Required |
|---|---|---|
| token | The OAuth access token you would like to revoke | Yes |
Request Examples
Response
On success, this API returns a 200 status code with an empty body
- Previous:Getting Started
- Up:Overview
- Next:File System API