API security

Most API:s requires that you include a subscription key with your request, and some API:s uses OAuth2 for elevated privilegies.

Each API will have the details in their own documentation, but here you get the quick overview and some recommendations.

Subscriptions

As a caller of an API, you most often will need a specific subscription for the product that the API is a part of. You can create a new subscription on the page for the product, and you can see all of your subscriptions for all products on your profile page.

Each subscription has two subscription keys: a primary key and a secondary key. This is to make it easier to roll new keys without interruption in your services.

It is recommended to roll your keys at least one or two times per year, to limit the possible misuse that can occur if a malicious user gets ahold of one of your subscription keys.

If we detect that a subscription is misusing any of the API:s, we will cancel that subscription. If you yourself detect that someone seems to be using one of your subscription keys, you can update your application to use the other key, and then roll the key that is being mis-used.

We recommend all developers to create and use their own subscriptions during development and test. In verification and production however, a developer subscription should never be used. Instead you should register a user for your organization, and create very specific subscriptions for each combination of your application and the product it needs to use. This is to ensure that if one of your applications subscriptions gets cancelled, your other application are not affected.

We do not enforce any type of naming-scheme for your subscriptions, but we do recommend that the names should clearly state which application that uses it, and for what purpose.

Using a subscription in a request

Most API:s allow you to specify the subscription key either as a query parameter, or as a HTTP header. We recommend the header-approach, but during development it is sometimes simpler to just add it as a query parameter instead.

Unless otherwise stated in the documentation for the API, the name of the query parameter will be subscription-key, and the name of the header will be Ocp-Apim-Subscription-Key.

OAuth2

Some API:s needs a bit more serious security than subscriptions can provide, and therefore they require an access token.

To be able to request an access token, your application must be registered and be assigned the privilegies needed to perform its tasks. To get your application registered or to request further privilegies, you need to contact us via e-mail and include the following:

  • E-mail adress of your organization-user. This is so we can verify that you have created such a user, and this is also where we will send the resulting credentials.

  • The name of your organization and the application thats needs the registration and/or extra privilegies. Also include information about wether it already is registered, or if it should be a new registration.

  • The name of the product(s) and the API(s) that you require access to. Also include, per API, what kind of access you need. The documentation for each API will list what kind of access you can request.

  • Which environments you need access to, per API. The documentation for each API will list their available enviroments. The same registration is used for all environments, but access is given per environment.

When we have received your request, it will be controlled and verified by the system owner, and after a couple of workdays you should recevie an answer, and possibly your new credentials.

Acquiring an access token

When your application needs to call an API that requires OAuth2, first it needs to acquire an access token. This is usually done via the client credentials flow, where your application authenticates itself using either a client secret or a client certificate.

With the request to acquire an access token, your application needs to specify its intent, that is it has to specify what scope the token should be valid for. This scope is different for each product, and possibly for each API within a product. The documentation for the API will specify the exact value you should specify as scope for that particular API.

An access token is valid for a short period of time, so your application needs to be able to request a new access token as needed. But the same token can be used in several calls, as long as it is still valid.

When calling the API, you will include the access token. The documentation for the API will specify in what way it can receive the token, but in most cases this is via the Authorization-header, with type Bearer.

This is classic OAuth, but below you can see a simple example of how it may be performed:

// Request the access token
var apiScope = "api://.../.default"; // The scope most often looks a bit like this
var tokenResponse = RequestAccessToken(apiScope); // Calls the token-endpoint, authenticating with suitable credentials
var actualToken = tokenResponse.access_token;
var expiresAt = Now.AddSeconds(tokenResponse.expires_in);
var apiResponse = CallTheApi(useBearerAuthorization=actualToken);
...
// Some moments later, we can check `expiresAt` to see if the token is still valid, and if so we can use it again in another call
...

The request to the API includes the access token as the value of the authorization header:

HTTP POST /api/resource
Authorization: Bearer ...token-value...