Authentication

Important!

We will have supplied you with credentials to access our Results API. You and your organisation are responsible for the safe-keeping of these credentials. Please contact us immediately, should you ever suspect that these credentials have been compromised in any way.

---

API Key

You should already have been given an API Key, as you would have needed it to view this documentation.

You will need to present this as an HTTP header whenever you make a request on the API for access tokens or results data.

• Requests made without a API Key will return a response of 401 - Unauthorized
• Requests made with an invalid or expired API Key will return a response of 403 - Forbidden

---

OAuth2 Access Token

In order to get an access token, you'll need to make an HTTP request to our token endpoint, as follows:

• HTTP Verb: POST

• Endpoint: https://results-api.hgem.com/connect/token

• Headers:

  Name	Value
  hgem-api-key	Your API Key we have provided
  Content-Type	application/x-www-form-urlencoded

• Body:

  Name	Value
  grant_type	client_credentials
  client_id	Your Auth Client_ID we have provided
  client_secret	Your Auth Client_Secret we have provided
  scope (optional)	If omitted, your token will contain all the scopes assigned to the client. If you supply the parameter, you MUST include the scope hgem-results-api, plus any others you require, delimited by a space character. e.g "hgem-results-api visits/standard.read"

Example cUrl:

curl -X POST https://results-api.hgem.com/connect/token 
  -H "hgem-api-key: YOUR-API-KEY-GOES-HERE" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=client_credentials&client_id=YOUR-CLIENTID-GOES-HERE&client_secret=YOUR-CLIENT-SECRET-GOES-HERE"

Example Raw HTTP/1.1:

Below is an example request made by Postman

POST /connect/token HTTP/1.1
Host: results-api.hgem.com
hgem-api-key: YOUR-API-KEY
Content-Type: application/x-www-form-urlencoded
User-Agent: PostmanRuntime/7.11.0
Accept: */*
Cache-Control: no-cache
Postman-Token: 8b363c4e-e080-4189-bfa5-1deb3ae5bead,a7cec467-c39c-48c6-bd6c-92cfe2dd3d41
Host: results-api.hgem.com
content-length: 106
Connection: keep-alive
cache-control: no-cache

 grant_type=client_credentials&client_id=YOUR-CLIENTID&client_secret=YOUR-CLIENT-SECRET

Example using C#

The following uses the nuget package IdentityModel

using System;
using System.Net.Http;
using System.Threading.Tasks;
using IdentityModel.Client;

namespace HGEM.ResultsApi.Example
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            var client = new HttpClient();
            client.DefaultRequestHeaders.Add("hgem-api-key", "YOUR_API_KEY");

            var tokenResponse = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
            {
                Address = "https://results-api.hgem.com/connect/token",
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            });

            if (tokenResponse.IsError)
            {
                Console.WriteLine(tokenResponse.Error);
            }
            else
            {
                Console.WriteLine(tokenResponse.Json);
            }

            Console.ReadLine();
        }
    }
}

HTTP Response

A valid request will return a 200 - OK response that will contain a JSON object, with your access token available on the access_token property.

Access tokens are valid for 1 hour from when they are requested.

{
    "access_token": "Some_really_long_base64_encoded_text_that_makes_up_your_JWT_access_token",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "hgem-results-api visits/standard.read"
}

---

Making authenticated requests to the API

You now have everything you need to make authenticated requests to the Results API endpoints.

Every subsequent request you make on the API needs to be made with these two headers:

Name	Value
hgem-api-key	Your API Key we have provided
Authorization	Bearer Some_really_long_base64_encoded_text_that_makes_up_your_JWT_access_token

Unauthenticated requests will return a response of 401 - Unauthorized