Skip to content

API Authentication

This guide will walk you through the process of authenticating with the Ocean Data Platform API. The ODCat is currently in a closed release, so you will need to request access to the API. You can do this by contacting HUB Ocean at info@hubocean.earth or by contacting a member of the HUB Ocean team in our Slack channel.

Tip

Authenticating with the SDK is covered in the getting started guide, and SDK Quickstart guide.

Authentication using access tokens

In order to send requests to the ODCat API, you will need to obtain an access token (see below). Once obtained, the access token is used in the Authorization header of the request:

HTTP
# Example request providing an access token

POST /catalog/list HTTP/1.1
Host: api.hubocean.earth
Authorization: Bearer ${ACCESS_TOKEN}
Content-Type: application/json
Content-Length: 76

{
    "selectors": [
        {"kind": "catalog.hubocean.io/dataset"}
    ]
}

Obtaining an access token

Authentication is hard, and obtaining the access token is no exception. Our frontend services will make this process seamless, but developers who want to use the API directly will need to obtain the access token themselves.

In this section we will attempt to describe some common ways of obtaining an access token. This is not to say that these are the only ways, as there exist countless libraries and tools that can be used to obtain an access token.

The lazy way - copying the access token from Postman

If you only need to make a few requests to the API, you can use the access token obtained by requesting new access tokens in our postman collection. This assumes that you have access to the HUB Ocean postman workspace.

Tip

This token expires after one hour if it's not refreshed. This means that if you're copying the token from Postman, your token will eventually stop working. Using an authentication framework like the MSAL library - mentioned below - will refresh your token for you. The SDK has the MSAL library built in. When using the SDK in workspaces, or using the interactive login you only need to log in with your credentials.

Postman access token

  1. Open the "HUB Ocean" workspace in Postman.
  2. Click on the "API" view in the left sidebar.
  3. Make sure that the "ODCat PROD" environment is selected in the top right corner.
  4. Click on the "ODCat" API and make sure to pull any updates by pulling them in the git-pane on the right hand side.
  5. In the "ODCat" API, open the first folder named "ODCat" and click on the "Authentication" tab.
  6. Scroll down to the bottom of the page and click on the "Get new access token" button.
  7. A window should appear with an authentication-flow, identical to normal login-flows when accessing other ODP# services. Follow the instructions in the window to login.
  8. Once logged in, you should see a new access token appear in a new window. Copy the access token and use it in your requests.
  9. (Optional) To this the access token in postman, simply click on the "Use token" button in the new window.

The slightly less lazy way - using MSAL library

ODCat uses Azure Active Directory for authentication. The ODCat API is registered as a web application in Azure AD, and users can use the MSAL-library to obtain an access token. The msal-extensions python-package also comes with the ability to cache user credentials, so that the user does not have to login every time they want to use the API.

The following snippet lets users log in interactively:

python
import msal

# The client ID of the ODCat API
CLIENT_ID = "f96fc4a5-195b-43cc-adb2-10506a82bb82"

# The authority of the Azure AD tenant
AUTHORITY = "https://oceandataplatform.b2clogin.com/oceandataplatform.onmicrosoft.com/B2C_1A_signup_signin_custom"

# The scopes that the access token should have
SCOPES = ["https://oceandataplatform.onmicrosoft.com/odcat/API_ACCESS"]

app = msal.PublicClientApplication(CLIENT_ID, authority=AUTHORITY)

# Get the ID and refresh tokens
app.acquire_token_interactive(scopes=SCOPES)

# Acquire the access token
token = app.acquire_token_silent(scopes=SCOPES, account=app.get_accounts()[0])

access_token = token["access_token"]

# Use the access token in your requests
# ...

The hard way - manually obtain an access token using requests and client credentials

If you are so inclined - and you have the necessary client credentials - you can also obtain an access token using the requests library. The following snippet shows how to do this:

python
import requests

# The client ID of your application
CLIENT_ID = "a1b2c3d4-1234-1234-1234-1234567890ab"

# The client secret of you application
CLIENT_SECRET = "SUPER_SECRET"

# Scope of the access token
SCOPE = "https://oceandataplatform.onmicrosoft.com/odcat/.default"

# Token URI
TOKEN_URI = "https://oceandataplatform.b2clogin.com/oceandataplatform.onmicrosoft.com/b2c_1a_signup_signin_custom/oauth2/v2.0/token"

res = requests.post(
    TOKEN_URI,
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": SCOPE,
    }
)

res.raise_for_status()

token_dict = res.json()

# Optionally - validate the token

access_token = token_dict["access_token"]

# Use the access token in your requests
# ...