Getting Started with OAuth 2.0

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).

App Setup
Create an app

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 apisupport@hellosign.com 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 attributes
Field Description
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 and billing

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.

Scopes where users are charged
Name Value Description
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.
Scopes where the app owner is charged
Name Value Description
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.
App Approval Process

In order to ensure that your integration adheres to eSignature regulations and best practices, we require all OAuth apps to email us at apisupport@hellosign.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.

Authorization

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.

Checking for an existing HelloSign account

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

{"account":{"email_address":"jack@example.com"}}

Response if the user does not have an account

{}
Authorization from existing users

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.

For example:

https://app.hellosign.com/oauth/authorize?response_type=code&client_id=cc91c61d00f8bb2ece1428035716b&state=900e06e2

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.

Retrieving the OAuth token

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

Example

Authorization from new users

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.

Example

Token Refresh

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

Example

Making API Calls

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]".

NOTE 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.

Example

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:

More Information

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".
http://www.quora.com/OAuth-2-0/How-does-OAuth-2-0-work