Picture

Developer Portal

Getting started

This page describes how to get started using the APIs exposed in the BOS APIM Gateway!

Sign up

All new users are required to first sign up. Go to the Signup page and follow the instructions. If you have already a bos.no account you can use it to directly sign in. If you are unable to do so it means that your account is not entitled to have access through the AD integration. In such case you can also follow the signup procedure using your BOS email.

User that are not BOS users need to get their account approved with their contact person in BOS after they have signed up. You also have to create a user for each environment.

Login

The Bertel O. Steen (BOS) API developmer portal requires login to view API documentation.

How to get access to the APIs

To invoke API's you need a subscription for the product that is linked to the API.

Sign in from the navigation menu to the left or the Sign in button above. If you don't have a bos.no user you can use the sign up functionality.

Create subscription

  1. Find the product you want to subscribe to. One API might be connected to several products but the subscription is always connected to a product.

  2. Navigate to the Create subscription, select the product, and create/select a SystemName for your subscription. Follow the rules for the naming convention for subscriptions. Approve the Terms of Use. Click Subscribe. This sends an approval request for the subscription into the BOS ticket system.

    • Client Id and secret related to OAuth will be provided in a secure manner by the Integration team after roles is selected and approved

Create subscription flow

Update subscription

  1. Navigate to My subscriptions that lists your current subscriptions. When a new subscription is submitted it has status "Submitted". When the subscription is approved you receive an email and the status of the subscription is changed to "Active".

  2. When the subscription is "Active" you have to go to Update subscription, there you can select active subscriptions and assign roles to them. Roles that are selected will go trough approval.

Create topic subscription

Create topic subscription, a subscription that is approved with system name is needed.

  1. Navigate to My subscriptions that lists your current subscriptions. When a new subscription is submitted it has status "Submitted". When the subscription is approved you receive an email and the status of the subscription is changed to "Active"

  2. When the subscription is "Active" you have to go to Topic subscriptions, there you can select active subscriptions and create topic subscription. Topic that are selected will go trough approval. Connection string will be sendt to user connected to system when topic subscription is implemented.

Get existing connections strings

  1. Navigate to Topic subscriptions that lists your current topic subscriptions. Select system and click send, this will send connection string to user connected to system.

Subscription Key

You have to specify subscription key in the header "Ocp-Apim-Subscription-Key".

You can get the subscription key for a specific subscription form the My subscriptions page.

To try the API you can navigate to the API operation of your choice and "Try it". The subscription list box is populated with your subscription key and you can fill in the request and invoke the API.

NB: To try an endpoint you need to add the "Authorization" header with a valid bearer token "Bearer {token}". Look at the section below for how to create this tokenHow to create an access token

How to create an access token

APIs require an access token (JWT) because they are using OAuth, in addition to the subscription key. Access tokens will be generated by a providing a dedicated client id and secret as described below. The same URL is used to issue tokens for the different environments. This URL is:

URL - https://login.microsoftonline.com/0abe8783-2c3e-4c42-9848-54e419bcdeb0/oauth2/v2.0/token

HTTP Example Request

POST /0abe8783-2c3e-4c42-9848-54e419bcdeb0/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id={clientId}
&scope={scope}/.default
&client_secret={clientSecret}
&grant_type=client_credentials

Variables

The clientId and clientSecret will be provided in a secure manner on the email added to the subscription. There will be issued one pair of clientId/clientSecret per environment.

NB: The clientSecret must be stored in a safe location (ex. Azure KeyVault) at your end!

NB: The clientId/clientSecret are dedicated to a particular system or team. They shall never be shared with another team or different system!

The scope variable shall be set to one of the below values depending on the environment you are working with:
TEST: https://api-test.bos.no
QA: https://api-qa.bos.no
PROD: https://api.bos.no

JSON Example Response

A successful response from the token endpoing will look like this:
{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

The access_token property should then be used in an "Authorization" header for endpoints in with the value: "Bearer {access_token}"

^

Other APIM environments

TEST

QA

PROD

^

Functionality in the BOS developer portal

The BOS developer portal supports information about

  • Available API's grouped by a logical information objects (Customer, Vehicle etc)

  • Available operations based on REST services. (GET, POST, PUT and PATCH)

  • Possibility to download OpenAPI definitions for API's to use in clients

  • Self service functionality for subscribing to products that is linked to API's (requires approval)

  • See report for user API activity

^

Powered by Bertel O. Steen central API Team