Authentication

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:

Authorization: Bearer 2v8q2bc6uvxtgghwmwvnvcp4

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.
  2. Handle the Response.
  3. Exchange the code for a token.
1. Initiate the Authentication Flow

Direct the user to the Egnyte OAuth 2.0 login screen using a request like this:

https://<Egnyte Domain>.egnyte.com/puboauth/token?client_id=<API Key>&redirect_uri=<Callback URL>&scope=<SELECTED SCOPES>&state=<STRING>&response_type=code
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 Space-delimited list of OAuth Scopes. 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:

https://apidemo.egnyte.com/puboauth/token?client_id=x2g35g8gynb5cedas649m4h4&redirect_uri=https://yourapp.com/oauth&scope=Egnyte.filesystem%20Egnyte.link&state=apidemo123&response_type=code

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:

https://yourapp.com/oauth?code=OAUTH_CODE&state=apidemo123

If the user denies your app, we redirect to:

https://yourapp.com/oauth?error=access_denied&state=apidemo123
3. Exchange the code for a token

Make a request to exchange the code for a token by sending an HTTP POST to:

https://<Egnyte Domain>.egnyte.com/puboauth/token

with the following form encoded ("application/x-www-form-urlencoded" format) request body:

client_id=<API Key>&client_secret=<Shared Secret>&scope=<SELECTED SCOPES>&redirect_uri=<Callback URL>&code=<CODE_FROM_STEP_2>&grant_type=authorization_code
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
scope Space-delimited list of OAuth Scopes. It must be the same as you used in the initial call to the authorization server.

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
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:

https://apidemo.egnyte.com/puboauth/token

With body:

client_id=x2g35g8gynb5cedas649m4h4&redirect_uri=https://yourapp.com/oauth&code=5u3m26mzgfn8nv6antmessr5&grant_type=authorization_code

Sample Response Body

{
  "access_token": "68zc95e3xv954u6k3hbnma3q",
  "token_type": "bearer",
  "expires_in": -1
}

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.

https://partner-integrations.egnyte.com/services/ 
https://us-partner-integrations.egnyte.com/services/

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:

<baseUrl>/services/oauth/code?redirect_uri=<clientUri>&client_id=<apiKey>

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

<baseUrl>/services/oauth/code?redirect_uri=<clientUri>&client_id=<apiKey>&domain=apidemo.egnyte.com

Example Initialization of Enhanced OAuth Flow

Initial Call:

https://partner-integrations.egnyte.com/services/oauth/code?redirect_uri=https://example.com/&client_id=<apiKey>&state=STATE

The above call will redirect to:

https://example.com/?state=STATE&code=st6b9tzzz5ck48x5yyauswv3

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:

  1. Initiate the Authentication Flow
  2. Handle the Response from Egnyte
Initiate the Authentication Flow
https://<Egnyte Domain>.egnyte.com/puboauth/token?client_id=<API Key>&redirect_uri=<Callback URL>&scope=<SELECTED SCOPES>&state=<STRING>&response_type=token
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 Space-delimited list of OAuth Scopes. 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:

https://apidemo.egnyte.com/puboauth/token?client_id=x2g35g8gynb5cedas649m4h4&redirect_uri=https://yourapp.com/oauth&scope=Egnyte.filesystem%20Egnyte.link&state=apidemo123&response_type=token

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:

https://yourapp.com/oauth#access_token=OAUTH_CODE&token_type=bearer&state=apidemo123

If the user denies your app, we redirect to:

https://yourapp.com/oauth#error=access_denied&state=apidemo123

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

POST /puboauth/token

With the following form-encoded parameters ("application/x-www-form-urlencoded" format) in the request body:

client_id=<Your API Key>&username=<Username>&password=<Password>&grant_type=password
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. 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

Request Examples

POST /puboauth/token HTTP/1.1
Host: acme.egnyte.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 91
Connection: close

client_id=cba97f3apst9eqzdr5hskggx&client_secret=8WkD6YhXJDZrV7kWABQtr2bXBUY5GRTmuqBpRs4JDWHkNNhSK9&username=test&password=password&grant_type=password
curl -v --request POST -H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=password -d username=test -d password='password' \
-d client_id=cba97f3apst9eqzdr5hskggx \
-d client_secret=8WkD6YhXJDZrV7kWABQtr2bXBUY5GRTmuqBpRs4JDWHkNNhSK9 \
https://apidemo.egnyte.com/puboauth/token

Sample Response Body

{
  "access_token": "68zc95e3xv954u6k3hbnma3q",
  "token_type": "bearer",
  "expires_in": -1
}

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, Workflows
Egnyte.permission Permissions
Egnyte.link Links
Egnyte.projectfolders Project Folders
Egnyte.bookmark Bookmarks
Egnyte.user User Management
Egnyte.group Group Management
Egnyte.audit Audit Reporting
Egnyte.salesforce Other Applications -> Salesforce
Egnyte.launchwebsession Embedded UI
Egnyte.controlleddocs Controlled Document Management
Egnyte.webhooks Webhooks

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:

  • 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):

GET /pubapi/v1/userinfo

Request Examples

GET /pubapi/v1/userinfo HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
				
curl -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
https://apidemo.egnyte.com/pubapi/v1/userinfo

Sample Response Body

{
  "id": 123,
  "first_name": "Test",
  "last_name": "User",
  "username": "test"
}
	

Revoking an OAuth Token

Call this API to revoke access to an OAuth access token

POST /pubapi/v1/tokens/revoke

With the following form-encoded parameters ("application/x-www-form-urlencoded" format) in the request body:

token=68zc95e3xv954u6k3hbnma3q
Variable Description Required
token The OAuth access token you would like to revoke Yes

Request Examples

POST /pubapi/v1/tokens/revoke HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
Content-Type: application/x-www-form-urlencoded
Content-Length: 30
Connection: close

token=68zc95e3xv954u6k3hbnma3q
curl -v --request POST -H "Content-Type: application/x-www-form-urlencoded" \
- H "authorization: Bearer 68zc95e3xv954u6k3hbnma3q" \
-d token=68zc95e3xv954u6k3hbnma3q https://apidemo.egnyte.com/puboauth/token
				

Response

On success, this API returns a 200 status code with an empty body