Skip to content

How to get access to the API

Overview

To be able to use the discover.swiss 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 muat talk to each other.

  1. Go to Get the Developer Portal and sign up for a account
    developer.discover.swiss
  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 yo get feednack from us you can access your keys in your profile in the developer portal.

if you have any questions get in contact with us and mail to support@discover.swiss.

Access control

It is important to know who's calling on our API and scince 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 do profide profile-tokens which work similar to OAuth2 token but are available without authentication. The identify 1 profile and can be used like a session token in 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 an 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

Language

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 server the default language which is German.

Subscription

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 request to /token endpoint to geta ProfileToken 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.

Info

In the MVP it was necessary to alway 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.

Note

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 month 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

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 applications a redirect uri like com.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" easy.

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

Here are a few ideas: https://stackoverflow.com/questions/14570989/best-practice-for-storing-and-protecting-private-api-keys-in-applications

And here a discussion by Google: https://cloud.google.com/endpoints/docs/openapi/when-why-api-key

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 easy 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 discover.swiss api, the key can't get stolen, but you need to maintain a "proxy", request get slower and we (discover.swiss) does 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 discove.swiss may charged on the traffic and then you would pay the traffic of the key thief as well.


Last update: June 26, 2020 05:12:50