Authentication and Authorization

Before you can interact with our APIs, your client application needs to get authenticated and authorized.

Our Public APIs contains two security layers, API Management and second is our Identity provider. All of your requests will be validated with both of the security mechanisms.

Basic flow for all API requests

  1. Get access token - Your app requests a token from our Identity Provider using its client credentials.

  2. Call the API – Include both headers:

    • Authorization: Bearer {access_token}

    • Ocp-Apim-Subscription-Key: {subscription_key}

  3. Validation - API Management checks the subscription key, then backend API verifies the access token with the identity provider. If both pass, the API executes the request.

Picture

Prerequisites

You need to get in contact with our Integration services support and ask for

Client credentials: Contains client identifier and client secret. This is used in our Client Credentials Oauth2 flow to validate and authorize your requests in the backend API.
Subscription-key: Fixed identifier for your client application. This will be send in the request's OCP-APIM-SUBSCRIPTION-KEY header
When contacting our support engineers, please provide at least these details:

Your name: 
Email address:
Phone number:
Application / Software name:
List of APIs you are interested:
Purpose of integration:

Code examples

Below some code examples for authentication and making the request with the access token

Request new access token and create a simple request

The code examples below creates a token request with client credentials and then makes a request to organization api using the token and subscription key.

The subscription key needs to have access to organization api and the client rights should be adjusted so it can access to organization info. Integration support team can make the needed adjustments.

  • Bash
  • PowerShell
  • Python
  • Javascript
  • .NET C#

Using the scripts in developer portal

The authentication part of the script examples above might get handy in this developer portal as well. If you have signed up and you want to use the "Try it" feature within the portal's APIs, you will need to submit the Subscription key and Authorization header with valid access token also in those requests.

Below is cleaned up script to get only the access token. Just follow the steps for each example comments, fill in the parameters with correct values, install dependencies (if required) and run the script. You should get an access token from our Identity provider which you can copy and use later.

  • Bash
  • Powershell
  • Python
  • Javascript
  • .NET C#

Using the access token in developer portal

After you have successfully fetched the access token, you can use it in the developer portal's "Try it" funciton.

API browser with some endpoint, just hit "Try it" -button, then add your subscription-key into "Subscription key" field and then click "Add header", name it as "Authorization" and paste your access token with Bearer text in front as a value and you should be good to go!

What's next?

Now that you have successfully implemented authentication, maybe you should check out how to setup postman with our APIs or maybe check out simple flow how to create sales invoices?