Accessing the API

Accessing the API#

Tokens will be obtained by the users via the Platform web application. The users will generate an MRV API token in their Client Admin interface.

An MRV API token is unique per client.

The token will have infinite life. Once generated, it will last forever.

If the Client is concerned that the token might have been compromised, or simply wants to follow a security policy of refreshing the token from time to time, the way of doing so is by generating a new token. Generating a new token will invalidate the existing one with immediate effect and only the new token will be valid in advance.

Note

The examples of API requests here are all using curl for general understanding and to be platform agnostic if any reader wants to try them.

Obtaining an API token#

As mentioned above, the token must be generated in the Data Platform. Therefore, the user will first need to be logged in to the Data Platform API.

curl -X POST "https://gateway.prod.hummingbirdtech.com/api/v1/login" \
     -H "Content-Type: application/json" \
     -d '{"email": "user@example.com", "password": "SeCrEt"}'

A successful login request will return a JSON response with an idToken field, which is the authentication token to be used to create an MRV token.

Now, the user must know the Client ID. If it yet doesn’t, the user can make a request to /clients API endpoint to get a list of available Clients (s)he belongs to (might be only 1, or more) and select from there the UUID of the Client that will be using MRV API:

curl -X GET "https://gateway.prod.hummingbirdtech.com/api/v1/clients" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <idToken>"

An example of that endpoint response for a user who is a member of 2 clients could be:

[
    {
        "name": "Megacorp Ltd.",
        "uid": "98401465-c03f-42ba-a1f3-e300674523f2"
    },
    {
        "name": "Fish Island Tech.",
        "uid": "2db4edf3-5a74-4ef6-aa51-74f80c94c429"
    }
]

Therefore, assuming for example that the user is a member of those clients and wants to use MRV API within “Fish Island Tech.”, this API request will create an access token for that client:

curl -X GET "https://gateway.prod.hummingbirdtech.com/api/v1/clients/2db4edf3-5a74-4ef6-aa51-74f80c94c429/api-token" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <idToken>"

where the response will return the Client UUID and the MRV API token:

{
  "token": "176633e96d0c2f0346c3eb4d0227d0fce64db20a",
  "client_uid": "2db4edf3-5a74-4ef6-aa51-74f80c94c429"
}

Warning

Once generated, the token will only be shown once, in that response JSON payload. The user must hence take note of the token and store it securely to use it in MRV API.

The token is stored encrypted in the Data Platform User Management database using Bcrypt algorithm, therefore is not possible at all to retrieve the original string of the token anymore. In case the token gets lost, the only way to get in again for the Client will be to generate a new token, which is a trivial operation as we have seen.

Performing authenticated API requests#

Once the token has been generated, the given Client can start making requests to the MRV API by adding an HTTP header ApiKey to the requests, which value of course will be the token.

Here is an example of a valid request, using the /fields MRV API endpoint to obtain a list of the fields registered to the Client:

curl -X GET "https://mrv-gateway.prod.hummingbirdtech.com/v1/fields" \
     -H "Content-Type: application/json" \
     -H "ApiKey: 176633e96d0c2f0346c3eb4d0227d0fce64db20a"

Note

Each request verifies the API token to authenticate the user. If there is any system error performing this token verification, the MRV API will return a 503 Service Unavailable response. This response means that the token is not necessarily invalid, but that the service could not verify it at this time.

Contents