OAuth

OAuth2 is a protocol that lets external apps request authorization to private details in a user’s Active account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

IMPORTANT NOTE

Active Passport handles the bulk of the OAuth logic. When your app passes a user to Passport and back for logging in, you will receive an access_token. You can then include this token in your calls to A3PI, either in the header or as part of the query string. A3PI will automatically use the auth token to determine which user you are acting on behalf of.

Web Application Flow

This is a description of the OAuth flow from 3rd party web sites. For more detailed info, consult the Active Passport Developer Guide

1. Redirect users to request Active Passport access

GET https://passport.active.com/oauth2/authorize

Parameters

client_id
Required string - The client ID you received from Passport when you registered.
redirect_uri
Optional string - URL in your app where users will be sent after authorization.
response_type
Required string - This field must contain the value code.

2. Passport redirects back to your site

If the user accepts your request, Passport redirects back to your site with a temporary code in a code parameter. Exchange this for an access token:

GET https://passport.active.com/oauth2/token

Parameters

client_id
Required string - The client ID you received from Passport when you registered.
redirect_uri
Optional string
client_secret
Required string - The client secret you received from Passport when you registered.
code
Required string - The code you received as a response to Step 1.
grant_type
Required string - This field must contain the value authorization_code.

Response

<OAuth>
  <token_type>bearer</token_type>
  <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
</OAuth>

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

GET http://a3pi.active.com/v2/users.json?access_token=...

Scopes

Scopes are not currently supported by Active Passport.

Scopes let you specify exactly what type of access you need. This will be displayed to the user on the authorize form.

More Information

It can be a little tricky to get started with OAuth. Here are a few links that might be of help:

Credits

This doc was heavily borrowed from GitHub. It has been modified for Active’s A3PI and Passport.