Skip to content

Authenticating with Hub

To start working with the Hub API, you’ll first need to authenticate with Hub.

Generating a token

Hub’s API uses the OAuth 2.0 Client Credentials Grant for authentication. First, you need to generate a client secret and client ID on Hub for use by your application. To do this, you need to create an API Client. API Clients are unique to each user, and use the roles and permissions assigned to that user to determine what the application is able to do with the API.

Note

API Keys can also be created at organisation level, these are no longer in use and will not work with the Hub API.

To create a new API Client, navigate to Back Office -> Users and then the user you want to create an API Client for. Click add new api client. This will allow you to name the API Client with a descriptive label. This label is only used for display purposes in Hub and will not be used as part of authentication.

You will then be shown a dialog with your client secret and client ID. This is the only time the client secret will be displayed, so make sure that you save it securely at this point. The client ID can be copied now or at a later time as it will display along with the descriptive label on the user profile to aid in identification. The client secret should be kept safe as anyone with the client secret and client ID will be able to access the API on the user’s behalf.

Important

It is not possible to retrieve the client secret after it has been created. If you lose it you must generate a new API client.

When you then want to log in to the Hub API, you need to use the POST /oauth/create_token endpoint with a Content-Type of application/x-www-form-urlencoded and your client_id, client_secret and a grant_type of client_credentials. Here’s an example POST body:

client_id=123e4567-e89b-12d3-a456-426614174000&client_secret=abcdefgh1234567&grant_type=client_credentials

The endpoint will then return a JSON encoded response with your temporary access token and an expiry time, e.g:

{
    "access_token": "abc123",
    "token_type": "Bearer",
    "expires_in": 3600
}

The expiry time is in seconds, and the token_type will always be Bearer. The access token can then be used for this amount of time.

To use the access token, when calling any authenticated endpoint, you should add an Authorization header with this bearer token e.g:

Authorization: Bearer abc123

Refreshing your token

Refreshing your access token is a matter of sending a new POST request to the /oauth/create_token endpoint as described above. This does not require the Authorization header to be set. Hub does not currently implement OAuth 2.0 refresh tokens.

TLS trust

OAuth 2.0 requires that the connection is secure. We achieve this by only offering the API over a HTTPS connection – in fact, the whole of Hub including the web interface is only available over HTTPS. We always use strong encryption, known secure cipher schemes, and certificates which are signed by publicly trusted CAs. We also publish a strict HSTS policy.

Currently, we use a certificate signed by Amazon to secure the connections. We strongly recommend that you enforce certificate validation including CRL checking.