Humatrix API

Getting Started

Welcome to the Humatrix API This documentation steps you through authenticating to the API, as well as the various endpoints and methods supported.

There’s two ways to connect to the API. Use Authorization Code if you’re making an add-on for other Humatrix users to use. Humatrix users to use. Use Password if you’re building an integration just for your own account.

API Authorization Code

Use Authorization Code authentication if you’re making an add-on for other Humatrix customers to use. For example, if you are building an integration that connects your custom reporting platform to Humatrix data, you’ll probably want to let lots of Humatrix customers use it. This is the approach for you.

First, you should create a new account for your app. Do this by signing up for a new account from the Humatrix homepage, then reach out to your Humatrix account manager and ask for the account to be set up as a developer account.

Once you have a dedicated account, you can get an application ID, secret, and redirect URI. You can get all of these from the applications page. With those details, follow these steps to authenticate a user using the Authorization Code authentication flow.

1. Redirect the user to the authorize endpoint

Allow users on your website to authenticate themselves with Humatrix by redirecting them to the following URL. Where APPLICATION_ID and REDIRECT_URI are the values specific to your app, and the scope parameter is the relevant Humatrix OAuth scopes your want access to (more information: Scopes ).

2. Catch the request to your redirect URI

The Humatrix server will then redirect the request back to your redirect URI, with a request code in the URL parameters. So if your redirect URI is https://mysite.com/callback then the request will be made to https://mysite.com/callback?code=AUTHORIZATION_CODE .

For local testing, as the browser gets redirected to the URI, it is possible to set it to a local address (i.e. /oauth/token/) to allow you to test your OAuth web app before deploying your code.

3. Make a POST request to the token endpoint

Now that you’ve got your authorization code, you can finally make the POST request to get your access token (don’t worry, this is the last step).

From your server/application make a POST request to /oauth/token/

The response should look something like this:

{
    "access_token": "M93zZC1KRVfU96PND6kpnJ1s7mvU0a",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write",
    "refresh_token": "64rBblHB15ozUvbJPYKDicdCvqEEfp"
}

Note : expires_in is in seconds, so your token will last 2 hours. To learn how to refresh your token, see Refreshing your Token. Refreshing your Token.

REFRESHING YOUR TOKEN

If you got your token using the Authorization Code authentication flow, and it expires, then using the refresh_token you got above, you are able to refresh it by making a POST request to /oauth/token/.

The response should look something like this:

{
    "access_token": "M93zZC1KRVfU96PND6kpnJ1s7mvU0a",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write",
    "refresh_token": "64rBblHB15ozUvbJPYKDicdCvqEEfp"
}

You can now go on using this new access token for another 2 hours.

Note : If your application’s access is revoked by the user, then you will need to run through the authentication process again to obtain a new access token.

Note : Although the tokens only last for 2 hours, you can refresh your token as many times as you want. The refresh token has no expiry but can only be used once.

API Authorization Password

Use Password authentication if you’re building an integration just for your own account. For example, if you’re building an integration for a specific customer - either as an in-house developer or as a consultant - this is the the approach for you.

If you’re using the API for a single account, the Password authentication flow is an easier way to get set up. You can authenticate via the command line using your Humatrix login details, or you can just set up an access token through the Humatrix APImanagement page.

Access tokens generated using Password authentication never expire, but can be revoked from the API management page.

Make a POST request to the token endpoint

From your server/application make a POST request to /oauth/token/ with the user’s email and password.

The response should look something like this:

{
    "access_token": "M93zZC1KRVfU96PND6kpnJ1s7mvU0a",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write",
    "refresh_token": "64rBblHB15ozUvbJPYKDicdCvqEEfp"
}

Note : Password authenticated tokens have no expiry. They can also be created and revoked from the access tokens page.

Scopes

In both the Authorization Code , Password you must specify the Scopes This is a complete scope list in the Humatrix API. In addition, each destination specifies the scope to use.

Scopes	Endpoints	Description
`read` , `write` , `group`	Users	Access information about the current user.
`report`	Users,Document	Manage document updates and shift document status.

Note : Scope default read , write

API Endpoint (GET)


  https://hug.myhumatrix.com/oauth/token/


  curl https://hug.myhumatrix.com/oauth/token/ -X POST -H "Cache-Control: no-cache" \
  -F "grant_type     = password"\
  -F "username       = YOUR_EMAIL"\
  -F "password       = YOUR_PASSWORD"\
  -F "client_id      = YOUR_APPLICATION_ID"\
  -F "client_secret  = YOUR_SECRET"\
  -F "scope          = YOUR_SECRET_SCOPE"

API Documentation

Humatrix API

Getting Started

API Authorization Code

API Authorization Password

API Endpoint (GET)