Application registration and authentication

Table of contents:

Intended audience

This page is intended for software developers who would like to access our API in order to build their own applications based on the data gathered and combined by Barentswatch. 

Prerequisites, licencing and crediting

To use the BarentsWatch API you have to register your application with BarentsWatch. Please see: https://www.barentswatch.no/om/apnedata/ 

Information about how to obtain an API user: Please see www.barentswatch.no/om/api-vilkar (Norwegian) or send an e-mail to post@barentswatch.no 

Open ID Connect flows

The BarentsWatch API supports Open ID Connect flows like client credentials, authorization code, and device code. Self registered clients only supports client_credentials. You have to contact BarentsWatch to set up other types of clients.

The OpenID discovery document is here: https://id.barentswatch.no/.well-known/openid-configuration (production).

How to request an access token

You need ClientID and ClientSecret from self-registration on MyPage/Minside, or obtained from BarentsWatch.

How to use the access token

An application can obtain a token for use with the BarentsWatch API by posting a token request via HTTPS to https://id.barentswatch.no/connect/token:

• Use HTTPS POST
• URL must be id.barentswatch.no/connect/token
• Header 'content-type' must be 'application/x-www-form-urlencoded'
• Body must have four key-value pairs, separated by ampersand (&):
  • Key 'grant_type' must have value 'client_credentials'
  • Key 'client_id' must have your full client ID as value, which is often written like this: myusername@example.com:myclient. If your client does not url-encode automatically, you must url-encode it like this: myusername%40example.com%3Amyclient
  • Key 'client_secret' must have a client secret you have created, as value.
  • Key 'scope' must have value 'api'

Example request, using curl:

curl -X POST --header "Content-Type: application/x-www-form-urlencoded" -d "client_id=YOUR_CLIENT_ID&scope=api&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials" https://id.barentswatch.no/connect/token

Example success response:

{
  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type":"bearer",
  "expires_in":3600
}

More information: https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/

How to use your access token to access the API

This is an example request to the BarentsWatch API to get available forecast times for a particular fairway.

GET /bwapi/v1/geodata/waveforecast/available/?modelname=folda&fairwayid=1 HTTP/1.1
Host: www.barentswatch.no
User-Agent: My Application Name
Content-Type: application/x-www-form-urlencoded
Authorization: bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3

The same request using curl:

curl -X GET "https://www.barentswatch.no/bwapi/v1/geodata/waveforecast/available?modelname=folda&fairwayid=1" --header  "accept: text/plain" --header  "Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3"

These external websites might be useful for developers:

• List of OAuth libraries: https://oauth.net/code/
• About client_credentials grant https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/

How to log in to the OpenAPI documentation

You can log in to the OpenAPI-documentation with your own client.

• Go to https://www.barentswatch.no/bwapi/openapi/index.html
• Click 'Authorize'
• Below the headline "oauth2 (OAuth2, clientCredentials)":
  • Replace client_id with your own client_id. It has to be URL-encoded like this: myusername%40example.com%3Amyclient. You can copy your URL-encoded client_id from MyPage/Minside.
  • Enter your client_secret
  • Select 'api' scope (tick the box)
• Click 'Authorize', and then 'Close'

You are now logged in.

You can select the API documentation in the dropdown-menu in the upper-right corner.