Skip to content

How to get access to the API


To be able to use the API you must register as a developer and we must onboard you as a partner. We will give you access to the test environment without the need to become a partner, but once you get productive we must talk to each other.

  1. Go to Get the Developer Portal and sign up for an account
  2. The Team will get a notification and assign you a subscription for the test environment.
    Although there are several API's you can choose from, with a test subscription you can access all of them
  3. Once you get feedback from us you can access your subscription keys in your profile in the developer portal.


If you have any questions get in contact with us and mail to

Access control

It is important to know who's calling on our API and since we do not provide a UI the application provider (you) must provide the correct identification tokens to get access to the API and the data. All these tokens are sent in Request Headers.

Identification levels

identification levels

Based on the subcription-key we can identify the partner and the application which is calling. The Partner information we need to filter data especially in the profile service.
-> Ocp-Apim-Subscription-Key header

We do provide a (technically) sessionless REST API. But to support the requirement of "as-a-guest" orders and profiles without log-in (authentication) we use profile-tokens which work similar to OAuth2 token but are available without authentication. To identify 1 profile and can be used as a session token on the web or stored in a client app to persist the connection to the current profile.
-> ProfileToken header

When a client application offers authentication to a user using our Azure Active Directory B2C, the guest can log in with different social media providers or user/password. In this case, you can use standard OAuth2 or openID connect flows to log the user in and provide the Authorization Bearer token to access the API.
-> Authorization header

In the future, we will distinguish between users who logged in with a social account where only the E-Mail is verified or for example with swisspass or suisseID where we can rely on the identity of the user.

Request Headers


Accept-Language: {iso-2 language code}

All APIs accept Accept-Language header with two letter ISO (en, de, fr, it) code to request content in different languages. If a language is not available or the header is missing it will serve the default language which is German.


Ocp-Apim-Subscription-Key: {subscription key}

You will need to include the appropriate subscription key you can get in the developer portal in EVERY request to API.

Profile Header

ProfileToken: {jwt}

Without a valid ProfileToken or an Authorization header it is not possible to access the profile or marketplace services.

  1. Make a request to /token endpoint to get a profile token token and store it locally similar to a session cookie.
  2. In the token response you will get a refresh token as well. This token can be used to refresh the profileToken after (or better just before) it expires.


In the MVP it was necessary to always add a ProfileToken. But for easier handling in Apps which use the profile service only with authenticated users we changed the behavior so that an Authorization header only is sufficient too. If both are present they need to fit the same profile.


The desired maximal lifetime of the refresh token can be set in the token-request as well. Not in all scenarios the same lifetime of the refresh token makes sense. For client apps a longer lifetime is better so the user is still "logged in" even after several months of not using the App. But on a web application this is a more serious security issue and the refresh token should only be valid for the duration of an expected user "session".


Authorization: Bearer {jwt-token}

We use Azure Active Directory B2C as an identity server and standard OAuth2 which means you need to include the Authorization Header sending the Bearer{{access token}} in every request. This token identifies the user and is used to select the profile to work with (not query parameters).

Before you can use it in your application we need to register it in the tenant and you will get the App Key. To do so we need

For Webapps (like our sample app): the redirect Url like

Sample and client libraries you can find here:

For native client application, iOS application and Android applicationsaredirect uri likecom.onmicrosoft.contoso.appname://redirect/path is required too and detailed information can be found on the linked pages.

Best practices

Where to store the API-Subscription Key

Generally ,subscription keys used on the client can be "stolen" easily.

On the topic of how and where the API Key is stored in the app, there are different opinions. Our key must be handled in the same way as any API key from Google or DropBox or somebody.

Here are a few ideas:

And here a discussion by Google:

If you compile the subscription key in the app it is very hard to change it in case it gets stolen and misused. If you get the key from your server (your own API). It can be changed easily and without a new release. In the end, however, it also requires an access authorization to your API and the problem will only be postponed. If you communicate only through a proxy on your server with the api, the key can't get stolen, but you need to maintain a "proxy", request get slower and we ( do not get useful tracking information from the client directly which can be used for monitoring and DOS detection.

The subscription key is only enough to use the API. But that does not give you any external data, you can only use the services and reload the data you save yourself.

At some point in the future may charged on the traffic and then you would pay the traffic of the key thief as well.



A project will be assigned to you which contains all the data requested by your specifications. For example, special entities "Events, tours, POI, etc.". Moreover, the entities can be located in a particular region or desired structure of administrative areas. It is important to include the assigned project code as the query parameter.

For more information see Infocenter service endpoints.

Last update: September 30, 2021 16:13:00