Authenticate
To authenticate with our services, use one of the following authentication modes:
OAuth2
The Authentication can be performed in two different way by using: * Client credentials. This type of authentication is suited to cases when the third-party software is a backend system. * Authorization code. This type of authentication is suited to cases when the third-party software is a web application.
OAuth2 authorization code
The Authentication flow with an authorization code is the follow:
* The user performs an action that requires the 3-P webapp to get a valid token for Connectors APIs
* The 3-P webapp redirects the user along with clientId and redirectUri parameters to the Connectors APIs /auth/authorize. It then shows the eSignAnyWhere login page
* After inserted the right credentials the authorization code will be given back to 3-P redirectUri
* The 3-P webapp uses the authorization code to request an access-token by calling the Connectors APIs /auth/token. This endpoint is protected with a basic authentication where username and password are the parameters clientId and clientSecret specified in credentials.
Credentials
If you don't have Connectors APIs credentials visit the Getting Started section
Request an authorization code
When the user perform an action on the third party web app that requires a valid auth session with the Connectors APIs it should make a:
GET /auth/authorize
Parameters
| Name | Description |
|---|---|
| clientId | It's the application identifier part of the credentials received from us during configuration phase |
| redirectUri | It's the third party application callback endpoint that knows how to treat the parameters code and state |
Use the authorization code to get an access token
The callback endpoint specified as redirectUri in the previous step should handle the request when the redirection flow terminate by sending back code and state parameter to it. It should then give the authorization code to obtain a access-token by making the following request:
POST /auth/token
Parameters
| Name | Description |
|---|---|
| grantType | authorization_code fixed value |
| redirectUri | Redirect Uri. It has to be equal to the one specified at the beginning of the authentication flow |
| code | Authorization code returned from authorize. Used only with grantType equal to authorization_code |
Authorization
A basic authentication is required by combining and encoding clientId and clientSecret
OAuth2 client credentials
The Authentication flow with client credentials is useful in scenarios where the client is a 3-P system:
* The 3-P system application has to perform an action that requires a valid token for Connectors APIs
* The 3-P system application request an access-token by calling the Connectors APIs /auth/token. This endpoint is protected with a basic authentication where username and password are the parameters clientId and clientSecret specified in credentials.
Credentials
If you don't have Connectors APIs credentials visit the Getting Started section
Use the client credentials to get an access token
To perform authentication with client credentials you have to perform an HTTP POST request:
POST /auth/token
Parameters
| Name | Description |
|---|---|
| grantType | client_credentials fixed value |
| redirectUri | Redirect Uri. It has to be equal to the one specified at the beginning of the authentication flow |
Authorization
A basic authentication is required by combining and encoding clientId and clientSecret.
Get user detail information
After authorization is completed you can get self user data. To retrieve personal user information you have to perform an HTTP GET request:
GET /auth/userinfo
Authorization
- A Bearer token authentication is required by specifying as value the JWT
access-token