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