OAuth v2

Requests to the AppHarbor API are authorized using OAuth2. The OAuth website lists several .NET libraries and examples that you can use to do OAuth authorization.

Register a Client

Register a client to get started. Registered clients are assigned a unique Client ID and Client Secret that you will use to identify your application when making requests to the API.

When registering a client, the following information is required.

Name Required The name of the application requesting authorization from users. Will be displayed on the authorization screen and in the authorized apps list.
Callback URL Required The URL AppHarbor will return the user to after authorization is complete.
URL Required The URL for your application.

Authorization Workflow

OAuth2 uses a multi-step authorization process to give you access to users' accounts. Follow the steps below to request authorization from users.

1. Redirect to the authorization page

From your app, direct users to a URL that follows the following format. Replace the token values with those specific to your registered client.

GET https://appharbor.com/user/authorizations/new?client_id=:client_id&redirect_uri=:redirect_uri

Parameters

client_id Required Provide the Client ID you received when you registered a client.
redirect_uri Required Provide the URL where the user will be redirected after access has been authorized. This must match the Callback URL associated with the registered client.
state Optional A user-defined value to be passed back to your redirect URL after successful authorization.

2. Retrieve authorization code from the redirect URL

When the user successfully authorizes your application they will be redirected back to your callback URL with the following information:

http://example.com/?code=:code

Extract the code parameter value. You will use this to retrieve the access token in the next step.

3. Request an access token

From your server-side code, make a POST request to https://appharbor.com/tokens with the following parameters request an access token.

Parameters

client_id Required Provide the Client ID you received when you registered a client.
client_secret Required Provide the Client Secret you received when you registered a client.
code Required Provide the code you received when the user accepted the access request.

Token Request Response

In response to the token request, the server will reply back with a plain text key/value representation of the access token. In .NET you can extract the value of the token like this:

// use the actual HTTP response body content in place of responseBody
var responseBody = "access_token=:access_token&token_type=:token_type";
var tokenData = HttpUtility.ParseQueryString(responseBody);
var accessToken = tokenData["access_token"];

Making Authorized API Requests

With the access token in hand, you can now make authorized requests on behalf of a user. In your request to the AppHarbor API, include the Authorization header as follows:

Authorization: BEARER :access_token

Alternately, you can specify the access token as a URL parameter.

GET https://appharbor.com/applications?access_token=:access_token

Back to overview

Token Expiration

Tokens issued by AppHarbor do not expire but the user has the option of revoking tokens at will. If you receive a HTTP 401 response to a valid API request, you should initiate the authorization workflow to obtain a fresh token.

Recent Discussions

22 Sep, 2014 10:05 AM
22 Sep, 2014 01:31 AM
20 Sep, 2014 01:28 AM
19 Sep, 2014 01:05 AM
16 Sep, 2014 11:22 PM