2. Authentication - signeasy/API GitHub Wiki

oAuth2 based Authentication

SignEasy uses the standard oAuth2 authentication for building multi-user integrations.

Registering your application

A registered client application is required to access the API endpoints protected by oAuth2. Please reach out to us at http://lp.getsigneasy.com/api-request/ for Client ID & Client Secret.

Client ID & Client Secret

Client ID, Client Secret, Redirect URI, Scope are the important attributes required for all further requests in generating authorization token.

Client ID will be represented as CLIENT_ID

Client Secret as CLIENT_SECRET

Redirect URL will be represented as REDIRECT_URI

Scope will be represented as SCOPE_STRING in the rest of this document.

Substitute these values for your client, in working out the rest of the document.

User authorization

Request user authorization

To request authorization for user's resources, redirect user to the authorization page at:

https://api-ext.getsigneasy.com/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPE_STRING

Scope will have to be from the list of available scopes separated by space

Retain the response_type as code

A prompt is presented to authorize the client application: alt Authorization page

Authorization redirection

If user approves authorization request, then the user is redirected to REDIRECT_URI with an authorization grant code as query parameter. Redirection URI along with query parameter will look like:

${REDIRECT_URI}?code=2K7iNbHeDRuwFLbpMImuoFETLmLnvH

Value of code parameter in the above URI will be referred to as GRANT_CODE in rest of this document.

If user denies authorization request, then the user is redirected to REDIRECT_URI with error query parameter set to access_denied. Redirection URI along with query parameter will look like:

${REDIRECT_URI}?error=access_denied

Access Token

Request authorization token

Authorization grant code should be used by the client application to acquire an authorization token. Authorization token is the final token that can be used to make further API calls listed at (https://github.com/signeasy/Himalaya-Doc-Writer/wiki/API-Endpoints).

A POST request at https://api-ext.getsigneasy.com/oauth2/token with the following query parameters should be used to acquire an authorization token:

  • client_id - CLIENT_ID
  • client_secret - CLIENT_SECRET
  • redirect_uri - REDIRECT_URI
  • grant_type - use authorization_code as the value for this parameter.
  • code - GRANT_CODE
Headers
Accept: application/json

Server responds with authorization token (access_token), scope for which token is applicable (scope), token type (token_type), duration after which token expires (expires_in) & refresh token (refresh_token). Sample output looks like:

{
  "access_token": "JqHyGD1SGIOSmjuVUIedOCnzLxjjXY",
  "scope": "pending:read",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "QalMjtiIldIjnXHQYWz0xuk1VazUSX"
}

Using access token

Every API call should be authenticated using the access token unless explicitly mentioned. The access token is a bearer token which can be used in the Authorization header for every API call.

The value of the header would be Bearer JqHyGD1SGIOSmjuVUIedOCnzLxjjXY. Use this header in conjunction with the other required API parameters.

For example:

curl -X GET -H "Authorization: Bearer <Access Token>" https://api-ext.getsigneasy.com/v1/user

will return the user details.

Using refresh token

Every request made using token has a possibility of returning 401 Unauthorized response. It is possible that the authorization token has expired. At this point application should request for a new authorization token using refresh token received along with the authorization token.

To get a new authorization token make a POST request at https://api-ext.getsigneasy.com/oauth2/token with the following query parameters:

  • client_id - CLIENT_ID
  • client_secret - CLIENT_SECRET
  • grant_type - use refresh_token as the value
  • refresh_token - REFRESH_TOKEN

For example:

$ curl -X POST 'https://api-ext.getsigneasy.com/oauth2/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

Response will look similar to the response for authorization_code:

{
  "access_token": "JqHyGD1SGIOSmjuVUIedOCnzLxjjXY",
  "scope": "pending:read",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "QalMjtiIldIjnXHQYWz0xuk1VazUSX"
}

Revoking access tokens

Use this API to revoke an access token of a user.

To revoke an access token, use a DELETE API call using the same access token and the access token will invalidated for further use.

curl -X DELETE -H "Authorization: Bearer <Access Token>" https://api-ext.getsigneasy.com/oauth2/tokens/revoke/

On successful deletion, the response would be the following with a status code of 200.

{
  "message": "Access Revoked"
}

On failure, you would receive the following response with status code of 401.

{
  "message": "The server could not verify that you are authorized to access the URL requested. You either supplied the wrong authorization token, or you used an authorization token which doesn't have required scopes."
}

You are now ready to make API calls on behalf of the logged in user.

Next: What are the APIs available for you - (https://github.com/signeasy/Himalaya-Doc-Writer/wiki/API-Endpoints)