Authentication - UN-OCHA/hpc-api GitHub Wiki

This page provides guidance for authenticating with https://api.hpc.tools/.

Anonymous Access

It is not necessary to authenticate with the HPC API to interact with it, as there are many API endpoints that you can use to access public data.

Authentication only becomes necessary if you:

  • Need to increase your rate limiting (please contact us if this is the case)
  • Access non-public (e.g. unpublished) information
  • Modify information on HPC

Take a look at our guides for examples of how to use our API to access public data.

Authenticating as a person (via Humanitarian ID)

The primary method for authenticating with the HPC api is via Humanitarian ID (HID). Anyone can create an HID user account, and then authenticate with the HPC API as themselves.

If you have used any of the HPC.tools graphical applications (such as RPM or Projects Module), then you will have already used an HID account to log-in to that application.

To authenticate with HID, you need to generate a Token (our applications do this automatically using OAuth), and then send that token along with all API requests in one of two ways:

  • As a Bearer token:

    The most common way to send an auth token is as a Bearer token using the Authorization HTTP header (this is how HPC Applications work).

    For example, if your token was 8ec8c0bea8ec8c0bea8ec8c0bea8ec8c0bea8ec8, then you would make an API request like this:

    GET / HTTP/1.1
Host: api.hpc.tools
Content-Type: application/json
Authorization: Bearer 8ec8c0bea8ec8c0bea8ec8c0bea8ec8c0bea8ec8

    However, it may not always be possible to easily modify the raw HTTP headers of your requests, or it may make it hard to share queries and scripts in a safe manner.

    Note: Do not use this method if you are using PowerQuery, as it requires you to embed your token in your queries, which can be read by anyone you share queries with. Instead we recommend using Basic auth, see more below.

  • Using Basic auth:

    Most API clients have good support for Basic authentication (including PowerQuery).

    Authenticate with the username hid, and your token as your password.

    For example, if your token was 8ec8c0bea8ec8c0bea8ec8c0bea8ec8c0bea8ec8, then you could make an API request by either:

    • Including it in the URL: https://hid:[email protected]/...
    • Entering your details into the username / password fields of your API client

Authenticating in Excel

Excel has built-in support for Basic authentication when making API requests using PowerQuery. After you have generated a token, you will be able to use it to authenticate with the API in Excel Workbooks that use PowerQuery.

If you are opening a PowerQuery document that has been shared with you, you may be presented with a security warning like so:

Make sure that the document is from a trusted source before enabling content

If you go to refresh the query from the data tab that uses the API, or create a new query that connects to the API using Web.Contents, you will be presented with a dialog that looks like this:

  1. Select Basic on the left hand side, and you should be able to enter a username and password.
  2. Enter hid as the User name
  3. Enter your Token as the Password
  4. Make sure that the "Select which level to apply these settings to" is set to https://api.hpc.tools/. (This will mean that you only have to enter your login details once, and this will work across all of your excel workbooks).
  5. Click "Connect"

From this point onwards, all requests with the API will be done using your user permissions.

Clearing / Modifying Excel Authentication

You may want Excel to forget your login settings (for example, if you want to log in with a different token, or previously chose "Anonymous" access).

To do this:

  • Go to the "Data" tab at the top of the window

  • Select "Get Data" and then "Data Source Settings..."

  • Select the URLs that you want to modify authentication settings for, then select either "Edit Permissions" or "Clear Permissions" as needed.

Generating Long-Term HID Tokens

If you would like to have a long-term (non-expiring) token that you can use to authenticate as a person with HID, you can generate such a token from the HID documentation page by following the following steps:

  1. Visit the official HID documentation page: https://api.humanitarian.id/docs/

  2. Change the server selector to "Production server."

    (this will allow you to make API requests to HID directly from this page)

  3. Expand the "POST /jsonwebtoken " section:

  4. Click "Try it out"

  5. Enter your Humanitarian ID username & password in the textbox, making sure to keep the JSON format presented to you. (1)

    IMPORTANT: ONLY EVER ENTER YOUR HUMANITARIAN ID USERNAME AND PASSWORD IN OFFICIAL WEBPAGES AT https://api.humanitarian.id or https://auth.humanitarian.id

    Then Click "Execute" (2)

  6. Under "Responses", scroll to the bottom of "Response body" and copy the token. Make sure that you select everything between the quote marks (")

You can then send this token in the Authorization header with any requests as described above.

IMPORTANT: DO NOT SHARE THIS TOKEN WITH ANYONE, TREAT IT AS A PASSWORD

Authenticating as a system / bot / service

The HPC API also has mechanisms to support authenticating as a service, which allows for integrations with 3rd party services or dashboards etc...

There is currently no self-service mechanism for registering a service account with the HPC system, but if you have a need for this we can work out a solution for you.

Please contact [email protected] if you need to authenticate as a service.