Obtaining Authentication Credentials
Access to the jSign API is tightly controlled through the industry-standard OAuth2 protocol for authentication and authorization. Users of this API must obtain a bearer token, using their jSign API Key and API Secret, and then pass that token in as part of each API call they make, along with a valid username and password.
Note: Tokens expire after 4 hours. When your token expires, repeat the steps below to generate a new one for use with all subsequent API calls. Refresh tokens are valid for 60 days.
Step 1 – Convert Your API Key and API Secret to base64
Your API Key and API Secret will be sent to you as part of your jSign API on-boarding. If you do not receive your User ID, contact your Application Provider administrator.
- Take your Key and your Secret and open a base64 converter tool of your choice. For example, https://base64.guru/converter/encode/text.
- In the conversion window of your tool, concatenate your Key and your Secret thus — Key:Secret.
- Encode this string to base64.
- Take the resulting base64 encoded string and return to the environment where you have opened the jSign API collection (Postman, for example).
Step 2 - Obtain Your Bearer Token
Obtain your bearer token by making a POST {{baseUrl}}/api/v2.0/authorization/token request using Basic Authentication with your base64 string from Step 1.
-
Provide your username and password in the body, and put the base64 string in the Authorization field after the word "Basic:"
-
Click Send.
-
Use the resulting token when you use any of the calls in the jSign API. See Step 3 below.
A curl Example
The following curl sample is used to generate a bearer token:
curl --location --request POST '/api/v2.0/authorization/token' \ --header 'app_auth_type: jsign-oauth2' \ --header 'Authorization: Basic ODk3MTY5ZGItMWNiYi00MWIxLTk2ZDYtYjc0M2RkNWI5ZTY4OmNqNWFXam5ldEo=' \ --data-raw ''
- The request must be a HTTP POST request.
- The request must include a Content-Type header with the value of application/x-www-form-urlencoded;charset=UTF-8.
- The body of the request must be grant_type=client_credentials.
Receiving a Response
Upon successful authentication, the client/partner receives the following response:
HTTP/1.1 200 OK Status: 200 OK Content-Type: application/json; charset=utf-8
RESPONSE:
{
"message": "",
"data": {
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey [....]",
"refresh_token": "zf3bdBMbHc1gQW5sJbof8EfNLdRe0mbjP1BsQFLEINc=",
"token_type": "bearer",
"expires_in": 1618927271
}
}
Use the access token returned to exercise the other methods in the API, as described below.
Step 3 - Make API Calls with Bearer Token
The API methods can now be called using the bearer token. To do so, construct a normal HTTPS request and include an Authorization header with the value of Bearer <token value from Step 2>. In addition to the token, include any user or envelope ID needed if it is part of the request (other data values may be needed depending on the call in use).
For example, when calling the API method GET '/api/v2.0/envelopes/{envelopeId}/history':
REQUEST:
curl --location --request GET '/api/v2.0/envelopes/a3374969-02ff-4de1-a8b7-8882ae0db8b9/history' \ --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9' \ --header 'app_auth_type: jsign-oauth2'
RESPONSE:
{
"message": "",
"data": {
"envelope_id": "a3374969-02ff-4de1-a8b7-8882ae0db8b9",
"envelope_name": "Sample Envelope",
"envelope_history": [
{
"first_name": "Jon",
"last_name": "Smith",
"log_time_utc": "2021-08-20T07:01:10.79",
"content": "Jon Smith created the document",
"activity": "Created"
}
]
}
}
Note: Now that you are ready to use the jSign, you'll need to understand its System Characteristics, including allowable envelope sizes and supported file types.