SigningHub uses OAuth 2.0 to authorize client requests. The parameters required to authenticate a client application and retrieve an OAuth 2.0 access token are "grant type", “Client ID”, “Client Secret”, “User Name”, and “Password”. The “Scope” variable can be used when identifying a specific enterprise user or unregistered user (in case of electronic signatures needed from unregistered users in tight integration) as the target for operations.  Note this applies to virtually all calls except those related to digital signature operations.  

For such operations, for example in tight integration, the intended recipient credentials must be used as opposed to enterprise admin. The Authenticate API call returns an access token in the response which must be saved by the business client and must be provided with each subsequent API call as a bearer token for authorisation.  Note this token is used in tight integration scenarios for both digital and electronic signatures.

When invoking the refresh token option this will generate both a new access token for use, and refresh token for a subsequent refresh operation.  The refresh token operation means the correct grant type must be used, i.e. refresh_token, and the client_id and client_secret parameters are required.  User name, password and scope are not required.

Second Factor Authentication as OTP

If a user has OTP configured as a second factor authentication, this API will throw an error 403 with a JSON response of error and error_description. It will also send two response headers.

• x-otp
• x-mobile-number

x-otp will contain an access_token that will only be used to get an OTP token from OTP Login Authentication call. x-mobile-number contains phone number of the user that is found in the database. If SigningHub don't have a phone number for the user, it will be empty. 

If phone number is empty, application should ask for the phone number from the end user to send the OTP on the given number. For sending OTP, use OTP Login Authentication API call. 

Once OTP is received, client application will again call the following authenticate API to authenticate the user with two factors, i.e., Password and OTP. To submit the OTP request in the authenticate API a new request header is expected. 

• x-otp

This request header will contain the OTP that was received on the mobile. Server side will authenticate the user based on user email, password and also verify the OTP. Once everything is verified end user will receive the access token details. 

Terms & Services

After implementation of GDPR, SigningHub will enforce the end users to agree with new terms and services, every time there is a change in it. Calling authentication API end point will check if the user has provided proper authentication information. Once validated, it will also check if the user has agreed to the latest terms and services or not. If user has already agreed to the terms everything will work in the previous fashion. If new terms and services are found that are not agreed by the user the API will send following response header as false, along with access token details. 

• x-terms-agreed

https://api.signinghub.com/authenticate
HTTP Verb		POST
Content-Type		application/x-www-form-urlencoded
Accept		application/json
Request Body		grant_type=password& client_id=ACMEapp& client_secret=jr67gj0h76gr83nf8734nj59g4he895jh87nr& username=admin@ascertia.com& password=Password@12& scope=john@ascertia.com
Status Code	Message	Response Body
200	OK	{    "access_token": "454-j34jr67gj0h76nj59g4he895jh87n",    "token_type": "bearer",    "expires_in": 86399,     "refresh_token":"QUVTMjU2LUdDTZREjBjvyYJtYNpz9tV7EwYfdQ=" }
401	Unauthorized	{    "error": "account_locked",    "error_description": "Your account is temporarily locked for 30 minutes due to security reasons."   }
403	Forbidden	{    "error": "otp_required",    "error_description": "An OTP authentication is also required." }
		{    "error": "terms_of_service_required",    "error_description": "You must agree with the recent terms of service" }
		{    "error": "invalid_scope_user",    "error_description": "You are not allowed to authenticate using scope user. You must have manage users permission in your role." }
		{    "error": "account_disabled",    "error_description": "Account is disabled" }
		{   "error": "password_expired",   "error_description": "You must reset your account password." }
		{   "error": "reset_password",   "error_description": "You must reset your account password to access SigningHub. A reset password process initiated by the administrator." }
		{   "error": "inactive_account",   "error_description": "You must activate your account to access SigningHub." }
		{   "error": "create_password",   "error_description": "You need to set your account password to authenticate." }
400	Bad Request	{    "error": "invalid_request" }
		{    "error": "invalid_client" }
		{    "error": "unsupported_grant_type" }
		{    "error": "invalid_grant",    "error_description": "You have entered incorrect authentication credentials - try again" }
		{    "error": "unauthorized_user",    "error_description": "Users role doesn’t allow managing users" }
		{    "error": "incorrect_credentials",    "error_description": "The user email or password is incorrect" }
		{   "error": "inactive_account",   "error_description": "Your account has not yet been activated - you must click on the account activation link sent by email immediately after registration - check your inbox then also check your junk or spam folders" }
		{   "error": "refresh_token_revoked",   "error_description":"Refresh token is either invalid or expired" }
500	Internal Server Error	{   "error": "internal_error",   "error_description": "An internal server error occurred while processing the request" }

  

Item Details
Names	Description
Request Parameters
grant_type	Define the OAuth 2.0 grant type. It can be set to "password", "client_credentials", "refresh_token" or "active_directory". Note for most operations "password" is sufficient.  Active Directory is used when the authentication required is the user's AD credentials.  Client_credentials is reserved for internal use at this stage.
client_id	Application Name that you have configured in your Enterprise Account when configuring the integration options.
client_secret	API Key that you generated in your Enterprise Account when configuring the integration options.
username	SigningHub email address identifying the target user account - this can be an Enterprise Admin or an Enterprise User account.  Note an enterprise user can use an API Key created for the enterprise by an enterprise administrator.
password	Password for the account defined in the 'username' parameter.
scope (optional)	Used when the Enterprise Admin user is identified in 'username' and you wish to identify an Enterprise User as the target.  That is, set an enterprise user as the current user for operations.  For example, to update the general profile settings of an enterprise user then the "scope" variable can be used. If the business application directly identifies the Enterprise User and their Password for which the operations are required, i.e. in the "username" and "password" parameters, then the Scope parameter is not required. Note all operations except for digital signature signing can be performed on behalf of an enterprise user or unregistered user using this "scope" variable.
refresh_token (optional)	If access_token is expired, refresh token is used along with grant type refresh_token.  If refresh token is provided, username, password and scope attributes can be treated as optional.
Response Parameters
error	Error key to identify the error in programming and applications can respond based on the different error keys.
error_description	Error message against the error key returned. Client applications can present this error as it is or send their own error message.
access_token	OAuth user authentication access token - bearer token for subsequent authorisation to other API calls.
token_type	Type of the token returned by authorization server. It is always set to "bearer".
expires_in	Number of seconds for which this access token is valid.  Fixed value of 86,399 seconds (24 hours).
refresh_token	Refresh token returned by system to be used to regenerate access token