Authentication
In order to access the Vessel Insight (VI) APIs the requests must be authenticated. VI APIs uses OpenID Connect[↗️] and OAuth 2.0[↗️] protocols for authentication. Users must obtain access token from the authentication server and attach it as HTTP header when making requests to an API. In case of missing or invalid access token the server issues response with HTTP code 401 (Unauthorized).
Authentication servers
VI supports any standard OpenID Connect authentication server, Entra Id (fka. Azure Active Directory) is one of them.
In this case VI APIs relies on each customer having its own Entra Id with registered users and application registrations (clients).
Grant types
The VI APIs uses the standard OAuth 2.0 grant types (authentication flows) as well as one custom flow. Here are the most common use cases:
Client credentials[↗️] is used for API to API communication; in this case the "calling" API acts as "client", obtains access token using its client ID and secret and makes requests to other APIs using the access token.
Client credentials grant flow diagram
- tenant_id = Customer specific.
- client_id = Data user specific on the above customer tenant.
- client_secret = Data user specific on the above customer tenant.
- resource_id = Points to an environment in Kongsberg Digital.
Note on Client_Secret: The secret will expire and expiration date will be shared by the API team after activating the subscription.
Sample HTTP POST Request:
curl -L 'https://login.microsoftonline.com/TENANT_ID/oauth2/token'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'grant_type=client_credentials'
-d 'client_secret=your_client_secret'
-d 'client_id=your_client_id'
-d 'resource=RESOURCE_ID'
The response contains the access_token to be used in the API requests:
{
"token_type":"Bearer",
"expires_in":"3599",
"ext_expires_in":"3599",
"expires_on":"1730901110",
"not_before":"1730897210",
"resource":"RESOURCE_ID",
"access_token":"ACCESS_TOKEN"
}
Token lifetime
Access_Tokens have by default a lifetime of 1h, and the API consumer must ensure refreshing the token to avoid Access Denied (401) responses.
