Developer Center

Approver API Authentication Guide

The purpose of authentication is to verify a user's identity. In the browser, a user authenticates by entering a user name and password into a web form. For third-party applications that use the Approver.com API, there are additional considerations.

For security purposes, users must authenticate on the Approver.com login page (and nowhere else). To enable your application to retrieve user information through the Approver.com API without sharing the user's password with your application, your application obtains an authentication token. Your application then passes the authentication token to Approver.com web service API calls in lieu of the user's user name and password.

When authenticating with the Approver.com Web services API, there are two authentication flows:

  • The Web-based Authentication Flow, for Web applications
  • The Client Authentication Flow, typically used for applications that are installed on a user's machine, but also including other client applications such as desktop widgets, scripts, and any other application that is not capable of redirecting to the Approver.com login page

The type of application key you create determines whether your application uses the client method or the Web-based method. Web-based applications keys have redirect URLs that are used in authentication; application keys used for access by client applications do not. If you want to create an application key to use client authentication, don't specify a redirect URL at the time you create your application key.

Web-based Authentication Flow

Web applications redirect to the Approver.com login page to enable the user to authenticate. After the user gives the application permission, Approver.com redirects the user back to your application, passing a frob to your application in the form of a query string parameter. You designate the URL to which the user is redirected after authentication when you obtain an application key.

To obtain an authentication token from a Web-based application, your application goes through the following steps:

  • Direct the user to the Approver.com login page, passing your application key as a query string parameter in the URL:
    http://approver.com/login.aspx?app_key=myappkey00xx
  • The user authenticates with their Approver.com user name and password if they are not logged in already.
  • The user is directed to a permission page which gives them information about your application.
  • If the user agrees to give your application access to their account, a temporary authentication token, called a frob, is created.
  • The user is redirected to the redirect URL you specified when you created the application key. The frob is appended to the end of the URL:
    http://yoursite.com/yourpage.html?frob=yourfrob00xx
  • Your application makes a call to the Approver.com GetToken API to convert the frob into a permanent token.
  • Your application passes the permanent token with all subsequent Approver.com API calls made by this user.

Client Authentication Flow

For client applications, your application first obtains a frob programmatically using the GetFrob API. After you've obtained the frob, your application must open a Web browser to the Approver.com login page so the user can authenticate and give your application permission. After the user has authenticated, the login page directs the user to return to your client application. After the user has returned to the application, the application makes a GetToken call to obtain an authentication token. 

To obtain an authentication token from a Web-based application, your application goes through the following steps:

  • Place a call to the GetFrob API to create a frob.
  • Direct the user to the Approver.com login page, passing your application key and frob as query string parameters in the URL:
    http://approver.com/login.aspx?frob=myfrob00xx&app_key=myappkey00xx
  • The user authenticates with their Approver.com user name and password if they are not logged in already.
  • The user is directed to a permission page which gives them information about your application.
  • The user agrees to give your application access to their account.
  • Your application makes a call to the Approver.com GetToken API to convert the frob into a permanent token.
  • Your application passes the permanent token to all subsequent Approver.com API calls made by this user.

For both kinds of authentication, your application must be able to handle errors and deal with situations where an authentication token is invalid. Although an authentication token can remain valid for an extended period of time, your application should not assume that an authentication token will be valid forever. For example, in the future authentication tokens may be time-limited; it is also possible for a user to disable a token for a specific application.