OAuth

The Hail API implements the OAuth 2 standard for authentication. This can be used to gain delegated access to the Hail API on behalf of users.

To save yourself the hassle, it pays to use a pre-built OAuth 2 client for your language. For example:

league/oauth2-client for PHP
andreareginato/simple-oauth2 for Node.js

Create an application

In order to obtain your client_id and client_secret, you must first create an application in your Hail developers area. You will be able to name your application, get your OAuth credentials, configure your redirect URIs, and upload a logo.

Scopes

Clients using the authorization_code grant are allowed to request the following scopes:

id	description
user.basic	Access basic info about the logged in user, and list their organisations
user.manage	Access to edit user settings, create organisations and access their inbox
org.basic	Access basic information about organisations
content.read	Access to read content in the user's organisations: essentially, all GET requests on content resources
content.write	Access to modify content in the user's organisations: essentially, all POST/PUT/DELETE requests on content resources
content.connections	Access to manage connections in the user's organisations, and push content to them

You will receive an error when attempting to access and endpoint who's scope isn't valid for your access token.

Endpoints

Authorise

The endpoint where users should be redirected to authorise your application: https://hail.to/oauth/authorise. You must provide these fields in the query string:

field	required	type	description
client_id	yes	string	Your client / application ID
redirect_uri	yes	string	The URI on your web application where we should redirect the user after authorising. Must be a valid redirect URI for your application.
response_type	yes	string	The type of response we should redirect with, must be set to `code`
scope	no	string	A space-delimited list of scopes your application is requesting

An example request would be https://hail.to/oauth/authorise?client_id=RuYt53e&redirect_uri=http%3A%2F%2Fexample.com&response_type=code&scope=user.basic+content.read.

The user will be asked to grant your app the requested access. The user will then be redirected back to the URI you provide. If the request was approved, the URI will have a code parameter, and if not, it will have an error message explaining what went wrong.

Access token

The endpoint for obtaining an access token.

POST v1/oauth/access_token

Request Body

field	required	type	description
client_id	yes	string	The client / application ID
client_secret	yes	string	The client / application secret
grant_type	yes	string	The grant type, which will be `authorization_code`
code	yes	string	The code the user was redirected to your app from Hail with
redirect_uri	yes	string	The redirect URI used in the authorisation step

Response Codes

201 Created	Access token created successfully
400 Bad Request	Missing or invalid fields

Response Body

field	type	description
access_token	string	The access token to authenticate with the API
token_type	string	The type of access token, always 'Bearer'
expires_in	number	The number of seconds from the current time until the access token expires and needs refreshed
refresh_token	number	Used with the `refresh_token` grant to obtain a new access token

Example Response Body

{
    "access_token": "txmVnNC3lYiIRpPqFIETFbwk1hqAGjhlw63baLwn",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "EXk66boeiLEuuiBf33tHWXx7sEqdktSYh2wPsDak"
}

Refreshing an access token

Access tokens have a lifetime of an hour (3600 seconds), after which time they must be refreshed. This is a security feature of the OAuth 2 specification to prevent stolen access tokens from being usable indefinitely.

Any time an access token is created, an associated refresh token will also be provided. This refresh token can be used with the refresh_token grant to obtain a new access token to continue using the API. You will also be issued a new refresh token at the same time.

The same access token endpoint above is used, with the following fields:

field	required	type	description
client_id	yes	string	The client / application ID
client_secret	yes	string	The client / application secret
grant_type	yes	string	The grant type, which will be `refresh_token`
refresh_token	yes	string	The refresh token associated to the access token you want to refresh

Accessing protected resources

Once you've got yourself an access token, you can start accessing protected resources in Hail. You must present the access token in the Authorization header, like so:

GET https://hail.to/api/v1/some/protected/resource HTTP/1.1
Authorization: Bearer [access token]

Login

API Documentation