Authorization Code Flow

How to generate access and refresh token pair for multiple user applications?

Authorization code grant

🚧

Requires a new app to be created manually

Before you can use this authentication type, you'll need to create a new app manually with redirect_urls along with your basic access token from the portal. Please contact us at [email protected] and our API support team will assist you through the process.

This flow enables multiple Signeasy users to grant authorization to your app so you can access their Signeasy resources on their behalf. The flow involves three steps,

  1. Displaying the authorization consent screen to your users to review the permissions requested by your app to authorize and access their Signeasy account.
  2. Capturing the authorization code.
  3. Obtaining the access and refresh token using the authorization code, where the app shall then use the token to access the user's Signeasy resources via the API.

Step 1 - Authorization consent screen

GET https://auth.signeasy.com/authorize

Parameter

Type

Description

client_id

string

Required. The client ID you received when you created your app.

redirect_uri

string

Required. The URL in your application where users will be sent after authorization. The URL has to match one of the redirect urls set when you created your app.

scope

string

Required. A space-delimited list of scopes. To obtain a refresh_token along with the access_token you must include offline_access in the scopes.

response_type

string

Required. The value should always be code.

state

string

Optional. You can use the state parameter to mitigate CSRF attacks by using a unique and non-guessable value associated with each authentication request about to be initiated. This value allows you to prevent the attack by confirming that the value returned from the response matches the one you sent.

audience

string

required The unique identifier of the audience for an issued token, identified within a JSON Web Token as the aud claim. The audience value is always https://api-ext.signeasy.com/ for authorization code flow.

Step 2 - Redirect and capture the authorization code

When your users visit the URL, they'd see a consent screen requesting them to authorize your app to access their Signeasy account on their behalf within the scope of the permissions requested. Once they click on authorize and authenticate with Signeasy, they'd be redirected to the redirect_uri provided in the above step with a temporary code parameter in the URL. Capture the value of it to use it in the next step.

Step 3 - Obtain access and refresh tokens

Exchange the code you captured from the previous step for an access_token and refresh_token pair, by making the following request with the specified parameters.

Request

POST https://auth.signeasy.com/oauth/token

Parameter

Type

Description

client_id

string

Required. The client ID you received when you created your app.

client_secret

string

Required. The client secret you received when you created your app.

code

string

Required. The code you captured from the redirect URI.

redirect_uri

string

Required. The redirect_uri you used in the previous step.

grant_type

'string`

Required. The value for this step should always be authorization_code.

Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR…scvq",
    "refresh_token": "v1.MU7HbI3ZhvnKlROoRYz2…64",
    "scope": "rs:read rs:create rs:update original:read original:create original:update signed:read signed:create signed:update user:read files:read user:create template:manage app:launch rs:signingurl webhooks:manage offline_access",
    "expires_in": 2592000,
    "token_type": "Bearer"
}

How to use the access token in an HTTP request?

This access_token allows you to make requests to the API on a behalf of a user. You should include this access token in the Authorization header.

Authorization: Bearer ACCESS-TOKEN

curl -X GET -H "Authorization: Bearer <Access Token>" https://api.signeasy.com/v3/me

It is recommended that you securely store the refresh_token of your user, so that when the access_token expires, you can exchange the refresh_token for a new access_token and refresh_token pair without needing the user to grant authorization to your application often.

📘

Refresh Tokens

The refresh_token does not have an expiry time and can be consumed only once. When you use a refresh_token to generate a new access_token, you will receive a new refresh_token along with it. The old refresh_token then will be invalidated.

Refreshing the access token

The access_token you obtained always has a shorter lifetime. So eventually when it expires, you'll encounter the 401 Unauthorized response. You will need to obtain a new access_token using the refresh_token you obtained from the previous step. Make a POST request to the following endpoint with the specified parameters below to obtain a new access_token and refresh_token.

POST https://auth.signeasy.com/oauth/token

Parameter

Type

Description

client_id

string

Required. The client ID you received when you created your app.

client_secret

string

Required. The client secret you received when you created your app.

refresh_token

string

Required. The refresh_token you obtained from the previous step.

grant_type

string

Required. The value for this step should always be refresh_token.

Note: Every time you refresh an access_token you will receive a new access_token and refresh_token pair.

Revoking the refresh token

👍

Recommended practice

It is a good practice to rotate your refresh tokens by refreshing the token pair frequently in your code.

For the refresh token generated via authorisation code flow, you can revoke the refresh token by initiating the following request. Also, note that any fresh pair of access and refresh token generated will invalidate the previous refresh token.

POST https://auth.signeasy.com/oauth/token
curl --request POST \
  --url 'https://auth.signeasy.com/oauth/revoke' \
  --header 'content-type: application/json' \
  --data '{ "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "token": "YOUR_REFRESH_TOKEN" }'