Integration using OAuth 2.0

Developer documentation for secure integration with Huddle APIs

Standard protocol

Huddle uses the OAuth 2.0 protocol (proposed) for authorisation of requests to our
public APIs. OAuth is a mature standard which is widely discussed and implemented.
The protocol specification can be retrieved at:
http://oauth.net/documentation/spec/. This page represents an abbreviated
summary of the spec as implemented by Huddle. Unless otherwise indicated on this
page, our implementation conforms to the standard specification.

Is this a web application, a desktop application,
or an application running on a device?

Short description of your application

You should receive a confirmation of receipt of your request within one business
day. We aim to process all requests within three business days.

2.Obtaining End-User Authorisation

How to request authorisation to access a user's data through Huddle's APIs

When a user first uses your application, you will need to request authorisation
to access Huddle data on their behalf. This process requires the user to authenticate
with Huddle's authorisation server, and to agree to authorise access to their data
from your application. Once this process is complete, the authorisation server will
redirect the user back to your registered Redirect URI, including an Authoization
Code.

Reference: OAuth 2.0 Specification, Sections: 3 , 3.1

Collapse all

Expand all

Initial Request

Your code should issue a request to the authorize endpoint of Huddle's Authorisation
Server, as shown below:

This will typically cause the user-agent (e.g. browser) to issue a
GET to your registered Redirect URI.

GET /receiveAuthCode?code=ilWsRn1uB1
HTTP/1.1
Host: MyAppServer.com

Your application should save the Authentication Code from the querystring
code variable. However, if an error occurred during the process (e.g.
the user choses not to authorise the request), your application will receive a querystring
containing an error variable instead.

Handling errors

If the user choses not to authorise your application's request for access, or if
some other error occurs during the request process, the user-agent (e.g. browser)
will be redirected to your registered Redirect URI containing an
error variable, and no Authorisation Code will be included.

The error_uri variable contains the address of
a document which explains the error in more detail. The possible values of the error variable are defined in the OAuth specification,
and are summarised as follows:

Error code

Meaning

invalid_request

The request is missing a required parameter, includes an unsupported parameter or
parameter value, or is otherwise malformed.

invalid_client

The client identifier provided is invalid.

redirect_uri_mismatch

The redirection URI provided does not match a pre-registered value1

access_denied

The end-user or authorization server denied the request.

unsupported_response_type

The requested response type is not supported by the authorization server.

1 Your registered Redirect URI must match the URI included in the original
authorisation request. This URI is used to ensure that only your application can
successfully complete an authorisation request using its assigned client id.

Note that error codes invalid_scope and
unauthorized_client are not used by Huddle.

Sample code (C#)

In this sample we have created a class named HuddleAuthServiceAgent which is responsible
for interactions with the Huddle OAuth server defined by the OAuth protocol

This can be called to initialise the access token request. For example, the following
snippet could be executed from within an ASP.NET page code-behind file:

private void RequestEndUserAuthorisation()
{
// The user's browser will be redirected
to Huddle's Authorisation server which will
// then redirect the user back to the registered redirect URI (from web.config)
with
// an authorisation codevar authAgent = new HuddleAuthServiceAgent(newHuddleAuthConfiguration());
authAgent.BeginRequestEndUserAuthorisation(newHttpContextWrapper(Context)); }

3.Obtaining Access and Refresh tokens

How to use your authorisation code to obtain Access and Refresh tokens

Once you receive an authorisation code, you should request an Access token (and
its accompanying Refresh token) from the server. The Access token is the piece of
data which proves your authorisation to access data on behalf of the user. This
Access token expires after a set period of time (typically five minutes) and must
be refreshed by calling back to the authorisation server using the Refresh token.

The variables in the body should be replaced with values specific to your application,
with the exception of grant_type (and of course
code, which the server has supplied):

Key

Value

grant_type

Should be authorization_code. Other values are
not supported.

client_id

This should be your registered Client ID

redirect_uri

This should be your registered Redirect URI 1

code

The Authorization Code received from the server

1 Note that although you MUST include the redirect_uri
value, the Access token will be returned in the body of the server's immediate response
- not by using your redirect_uri. The redirect_uri value will be verified against
your registered Redirect URI to help verify that the client application still corresponds
to the details originally registered for the specificed client_id.

Typical response

If the Authentication code is determined to be valid by the server, a standard HTTP
200 response will be received, including the token data as the entity body of the
response using the application/json media type:

Details of these parameters (including scope -
which Huddle does not currently use for external access). Note that the
expires_in variable expresses the "time-to-live" of the access token,
expressed in seconds. After the token expires, it must be refreshed (see "5. Refreshing your Access token"below)

Handling errors

If the token request is invalid or unauthorized, an HTTP 400 response will be received.
This response also contains data encoded using the application/json
media type.

The huddleAuthServiceAgent.EndRequestEndUserAuthorisation call simply
passes the httpContextBase to the constructor of a class called
HuddleAuthCode was created to parse the return message from the server:

4.Calling the Huddle APIs

How to use your Access token when calling the API

On every call to Huddle APIs, your should include your access token as prove of
your authorisation to access data on the end-user's behalf. Your application should
be able to respond to error messages resulting from problems with the token.

As required by the OAuth specification, if the request contains an invalid access
token, or is malformed, the response from the server will be a 400 Bad Request,
401 Unauthorized or 403 Forbidden response, including a WWW-Authenticate header.

The error_uri variable contains the address of
a document which explains the error in more detail. The possible values of the error variable are defined in the OAuth specification,
and are summarised as follows:

Error code

Meaning

HTTP Status code

invalid_request

The request is missing a required parameter, includes an unsupported parameter or
parameter value, repeats the same parameter, uses more than one method for including
an access token, or is otherwise malformed.

400

expired_token

The access token provided has expired.

401

N.B. Although the OAuth2 specification also defines the error codes
invalid_token and insufficient_scope,
these codes are never returned by Huddle's APIs.

Sample code (C#)

Once the token has been retrieved, we call the Huddle API using a method named CallAPIEndpoint:

5.Refreshing your Access token

How to use your Refresh Token when your Access token expires

By calling the Authorisation and providing your Refresh token, you can obtain new
tokens. You will need to do this preiodically as the access tokens expire after
a short period of time (typically twenty minutes). Your application should account
for the possibility that the end-user has deauthorised your application in the period
since you last called the authorisation server.

Developers are encouraged to monitor the "time-to-live" of their access tokens and
to refresh their tokens before they expire. However, if an expired token is issued
with an API call, the API will reject the access request with the
expired_token code (see
"4. Calling the Huddle APIs, Handling errors").

Expired tokens can be refreshed using a request which is similar to the original
access token request: