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:
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.
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.
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.
The endpoint for obtaining an access token.
POST v1/oauth/access_token