OAuth API Authorization

Last Edited: July 17th, 2012

OAuth provides authorization for all AppDirect APIs. For more information on OAuth, please visit the Getting Started Guide.

Getting Started

You will need to obtain a developer key to sign each OAuth request to AppDirect. Each product on AppDirect will have its own set of OAuth credentials. These credentials will be visible under the "Edit Integration Settings" panel in the "OAuth configuration" section:

Clicking the "Generate developer key" will generate a new OAuth consumer secret. AppDirect currently only supports OAuth HMAC-SHA1 signatures.

Generating OAuth Requests

AppDirect's APIs support "two-legged" OAuth 1.0, also known as "signed fetch." Rather than obtaining OAuth access tokens, all requests will include a signed OAuth request in the Authorization header. The example below is to get a list of orders for an OAuth consumer "Dummy" using the developer key (i.e. OAuth consumer secret) value "secret":

GET /rest/api/events/dummyChange HTTP/1.1
Host: www.appdirect.com
Content-Type: application/xml
Authorization: OAuth realm="",
oauth_nonce="72250409",
oauth_timestamp="1294966759",
oauth_consumer_key="Dummy",
oauth_signature_method="HMAC-SHA1",
oauth_version="1.0",
oauth_signature="IBlWhOm3PuDwaSdxE/Qu4RKPtVE="

Note that the Authorization header should be contained on a single line. Line breaks have been inserted here for clarity. This signature may also appear in a URL query parameter as follows:

https://www.appdirect.com/rest/api/events/dummyChange?oauth_nonce=72250409&oauth_timestamp=1294966759&oauth_consumer_key=Dummy&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_signature=IBlWhOm3PuDwaSdxE%2FQu4RKPtVE%3D

Validating requests from AppDirect

All outgoing requests from AppDirect to a software vendor will be signed with that vendor's OAuth credentials. Vendors MUST verify these signatures to ensure that requests originate from AppDirect. Non-interactive requests sent between AppDirect and the vendor will contain an OAuth signature in the Authorization header. Interactive requests, where the user is redirected to the vendor, will contain a signature in the URL parameters.

Signing return URLs

With AppDirect's interactive callbacks, a user will be redirected to an application's website to complete some transaction (e.g. a subscription order). After completing that transaction on the application side, the application will redirect the user back to AppDirect. To ensure that the redirect comes from the application, a two-legged OAuth signature will be applied to the redirect URL itself.

For example, suppose a SUBSCRIPTION_ORDER event were passed with redirect URL:

https://www.appdirect.com/finishorder

Presume that the order is handled successfully and that the parameters "success=true" and "accountIdentifier=Alice" were being returned. Then the application would need to sign the URL:

https://www.appdirect.com/finishorder?success=true&accountIdentifer=Alice

This URL signed with with the OAuth consumer key "Dummy" and secret "secret" would be:

https://www.appdirect.com/finishorder?success=true&accountIdentifer=Alice&oauth_nonce=95009478&oauth_timestamp=1294967177&oauth_consumer_key=Dummy&oauth_signature_method=HMAC-SHA1&oauth_version=1.0&oauth_signature=sTmXIbI2QgUCroj9mIPBp6NPars%3D

Sample Code

Please review the OAuth Sample Code section for examples in different programming languages.