Get Authorization for API

How to authenticate in Enadoc API and get an access token to access Enadoc data resources?

Follow below steps to get authorization for Enadoc API.

Register client application

The external application should be registered in Enadoc Developer Portal (https://developer.enadoc.com) to access Enadoc resources. Once you registered the application, you will receive client_id and client_secret from the portal. If the client app is a web app, you must give redirect_ URL while the app registration process.

Parameters

client_id: Application id received through Enadoc developer portal client_secret: Application key received through Enadoc developer portal redirect_url: URL given to developer portal by the client. The OAuth code will be returned to this URL after login is successful.

Get Authorization

Use the client id and client secret to get the authorization URL from the system. Use the grant type as ‘authorization code’ when you request an access token and refresh token. You can access Enadoc resources via Enadoc API using this access token. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner’s user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

ENADOC-IDENTITY-PROVIDER (EIP) is responsible for providing identifiers for users who are looking to interact with Enadoc. User authentication is managed by EIP and all the user login information would be tracked. Enadoc organization information and user information also are managed by the EIP.

To access Enadoc resources through the Enadoc API, clients should have Enadoc website URL and the EIP URL.

Example for EIP URL: https://auth.enadoc.com

Below is the image of the Enadoc SaaS app URL, to understand what EIP URL is.

Get Authorization URL

POST [ENADOC-IDENTITY-PROVIDER-DOMAIN] /api/v3/authorization/url

After receiving client id and client secret via Enadoc developer portal, next use following format to create client authorization URL. Use your client id and redirect URL to get authorization url

Headers

Name	Type	Description
Content-Type	string	application/x-www-form-urlencoded
ClientId	integer	Client ID
RedirectUri	string	Redirect URI

200

{"url": "[ENADOC-IDENTITY-PROVIDER-DOMAIN]/oauth2/authorize?client_id=[Client ID]&redirect_uri=[Redirect uri]"}

If the client application is not a web application, will receive a response as below

{
  "url": "[ENADOC-IDENTITY-PROVIDER-DOMAIN]/oauth2/authorize?client_id=[Client ID]&redirect_uri=[ENADOC-IDENTITY-PROVIDER-DOMAIN]/login_success.html "
}

Authorization url will be displayed through web or mobile viewer which provide login to Enadoc users. After a successful login, an Oauth code will append to your redirect URL as below. You have to use the OAuth code to get an access token.

[YOUR-APPLICATION-REDIRECT-URL]?authcode=[Oauth-code]

Get Enadoc URL

GET [ENADOC-IDENTITY-PROVIDER-DOMAIN]/enadoc/discovery/api

After receiving Oauth code, client should obtain Enadoc API url from this endpoint through Enadoc Identity provider. Use response URL to consume Enadoc API.

Request Body

Name	Type	Description
oauth_code	string	After login success, this will appended to authorization url
client_id	string	Obtain through developer portal
client_secret	string	Obtain through developer portal

200 Enadoc API URL

{
  "ServiceEndpointUri": "https://portal.enadoc.com"
}

Get Access Token

POST [ENADOC-IDENTITY-PROVIDER-DOMAIN]/api/v3/token

Using this endpoint client applications can get access token and refresh tokens by changing grant type.

Headers

Name	Type	Description
Content type	string	application/x-www-form-urlencoded

Request Body

Name	Type	Description
grant_type	string	Refresh token or authorization code
client_id	string	Application ID
client_secret	string	Client Key
code	string	Authorization Code

200 Response consists of; token_type -> (A bearer token), expire_in -> (Token expire time) access_token -> (Token to access resources) refresh_token -> (Token to refresh accessibility)

{
"token_type":"bearer",
"expires_in":6000,
"access_token":"[Token]",
"refresh_token":"[Token]"
}

If you select refresh token as grant type, then you must enter only refresh token and you are not required to enter authorization code.

If you select authorization code as grant type, then you must enter only authorization code and you are not required to enter refresh token.

Requesting Authorization code: Request Body

{
  "grant_type": "authorization_code",
  "client_id": "[Your-client-id]",
  "client_secret": "[Your-client-secret]",
  "code": "[Oauth-code]"
}

Requesting Refresh Token: Request Body

{
  "grant_type": "refresh_token",
  "client_id": "[Your-client-id]",
  "client_secret": "[Your-client-secret]",
  "code": "[Oauth-code]"
}

Error Codes

Error code	Error	Error description	Reason
000.501	Invalid content type	Content type should be application/x-www-form-urlencoded	Content type not matched with application/x-www-form-urlencoded
000.001	Client_id is empty	Client_id should contain request body	Request body does not contain client_id
000.004	Client_secret is empty	Client_secret should contain request body	Request body does not contain client_secret
000.002	Invalid client_id	Client id is invalid	Requester sent invalid client_id
000.003	Inactive client	Client is inactive	Client application is in inactive status in developer portal
000.502	Invalid grant type	Grant type should be defined as authorization_code or refresh_token	Does not define grant type or does not match with required format
000.504	Authorization code is empty	Authorization code should contain request body	Request body does not have authorization code
000.506	Invalid authorization code	Authorization code is invalid	Requester sent invalid authorization code
000.507	Discarded code	Authorization code is already discarded	Access token obtained which requester sent authorization code
000.508	Refresh token is empty	Refresh token should contain request body	Request body does not contain refresh token
000.509	Invalid refresh token	Refresh token is invalid	Requester sent invalid refresh token

The scope which sounds the accessibility level for Enadoc resources by client application can be defined through the Enadoc portal.

Error code	Error	Error description	Reason
000.010	Library scope does not contain current application	Client has no library access permissions	Client does not have permission to access library resource
000.011	Tag profile scope does not contain current application	Client has no tag profile accessibility permissions	Client does not have permission to access tag profile resource
000.012	Index scope does not contain current application	Client has no index access permissions	Client does not have permission to access index resource
000.013	User scope does not contains current application	Client has no user access permissions	Client does not have permission to access user resource
000.014	Upload permission does not contain current application	Client has no upload permissions	Client does not have permission to upload document to Enadoc
000.015	Search permission does not contain current application	Client has no search permissions	Client does not have permission to search Enadoc
000.016	Tagging, flagging and commenting permission does not contain current application	Client has no tag, flag or comment permissions	Client does not have permission to tag/flag/comment documents in Enadoc

Each request should contain an authorization header to access each API method. Authorization headers should have the below format.

Header name: Authorization

Header value: bearer [token]

Following errors can occur when access token validation failed.

Error code	Error	Error description	Reason
000.510	Authorization token not found	Authorization token is not found	Authorization headers does not contain access token or Invalid header format
000.511	Invalid authorization token	Authorization token is invalid	Requester sent invalid access toke
000.512	Authorization token expired	Authorization token is expired	Requester sent expired access token