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.

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.

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.