OAuth allows you to perform actions on behalf of other users after they grant you the authorization to do so. For example, you could send signature requests on behalf of your users. This page lays out the basic steps to do that.
OAuth apps can either be setup to charge you, the app owner, or the user you are acting on behalf of. This choice is determined by which scopes you select for your app (detailed below).
Before you can do anything with OAuth, you will need to create an app.
Your app will need to be approved before anyone but you can authorize it. When you feel ready to go live, email us at firstname.lastname@example.org to request approval. You will be notified via email when the app is approved. Until then, you will be able to authorize it yourself and use it in test mode.
|App name||Your app will be presented to the user under this name.|
|Default OAuth callback URL||The URL to which the user will be redirected after they authorize your app|
|Event callback URL||The URL to which HelloSign should POST events. See the event section for more info.|
|Scopes||Actions that your app will be allowed to perform on behalf of the granting user.|
Scopes are divided into two sections: limited endpoint scopes that charge you, the app owner for requests made and full-access scopes that charge the user. The full-access scopes generally match to a section of our API with the signature request scope covering the "embedded" and "unclaimed draft" sections as well. These two types of scopes are mutually exclusive for billing purposes.
NOTE Once your users have authorized access to your app, any changes to the scopes on the app will remove this authorization and you will need to get their permission again to act on their behalf.
|Account Access||account_access||Access to basic account information, such as email address and name.|
|Signature Request Access||signature_request_access||Access to send, view, and update signature requests and to download document files.|
|Template Access||template_access||Access to view, create, and modify templates.|
|Team Access||team_access||Access to view and modify team settings and team members.|
|API App Access||api_app_access||Access to view, create, and modify embedded API apps.|
|Basic Account Info (limited)||basic_account_info||Access basic account information, such as email address and name.|
|Send Signature Requests (limited)||request_signature||Send signature requests, access statuses and document files.|
In order to ensure that your integration adheres to eSignature regulations and best practices, we require all OAuth apps to email us at email@example.com when ready for approval.
NOTE We recommend you test your own app prior to requesting approval. You can do so by authorizing your own account.
A user needs to authorize your app before you can act on his behalf. Once they do, your app will be granted an access token which can be used for authentication when making requests on behalf of your users.
There are two major authorization scenarios, one for existing users and one for new ones. This is why we provide a way for you to check if a user exists.
Response if the user has an account
Response if the user does not have an account
Existing HelloSign users can authorize your app by going to your app authorization page. The URL can be derived from the app client id and state token of your choice.
NOTE The "state" parameter is used for security and must match throughout the flow for a given user. It can be set to the value of your choice (preferably something random). You should verify it matches the expected value when getting an OAuth callback.
Before reaching the authorization page, they will need to login or signup. Once done, the user will be shown the name of your app, the list of actions (scopes) being requested and two choices will be offered.
• If they click "Accept" they'll be redirected to the callback URL you specified when creating the app.
The URL will contain a code parameter and the same state parameter as in the authorize URL.
• If they clicked "Deny", only the state parameter will be present.
Once you have retrieved the code from the user callback, you will need to exchange it for an access token via a backend call. Make a POST request to https://app.hellosign.com/oauth/token with the following parameters:
|state||Same as the state you specified earlier|
|code||The code passed to your callback when the user granted access|
|grant_type||String value of "authorization_code"|
|client_id||The client id of your app|
|client_secret||The secret token of your app|
If the user does not already have a HelloSign account, you can still send them to the authorization page and they will have to signup at that point. Preferably, you will want to avoid this. Instead you should create an account and get the authorization data at the same time.
Your app has to be approved before you can do this.
NOTE In this case, the authorization is implicit and the user will receive an email asking them to confirm the access being granted. Your app will not be able to perform actions on behalf of users this way until they confirm.
Access tokens are only valid for a given period of time (typically one hour) for security reasons. Whenever acquiring an new access token its TTL is also given (see expires_in), along with a refresh token that can be used to acquire a new access token after the current one has expired.
Make a POST request to https://app.hellosign.com/oauth/token with the following parameters:
|grant_type||String value of "refresh_token"|
|refresh_token||The refresh provided when you got the expired access token|
Now that you have an access token, you can now make API calls on behalf of other users. When making API calls, you'll need to pass the access token in the authorization header with the following format: "Bearer [access_token]".
You will only be able to see users' signature requests that were created using your API app.
This means that if the user receives or sends a signature request themselves, your API calls using the access token won't be able to see them.
Signature Request with OAuth
To send a signature request with an automatically appended signature page, let's take the cURL example from the signature_request/send documentation and replace Basic authentication with OAuth authentication:
Here are a few links to read up on related topics and get a better understanding of our API.
|http://oauth.net/2/||OAuth 2 Protocol information. For users with existing accounts we use the "Authorization Code flow". For users without existing accounts we use a hybrid of the "Authorization Code flow" and the "Resource Owner Password Credentials flow".|