clientid overview.html - swisscom-api/doc GitHub Wiki

title: Client Id Overview owner: API

<%= modified_date %>

Authenticating API calls with client_id, an overview

The client id is a unique key that is assigned to each client of Swisscom's APIs during the onboarding process. A selected number of APIs will accept this key as sufficient proof of identity for the authentication process.

Note: Client Id has many different synonymous: 'API keys', 'apiKey', 'app keys', and 'consumer keys'.

Benefit: simplicity

APIs that accept client id for authentication, only look for a HTTP request header or querystring parameter client_id:xxxxx. For the developer that's the easiest way to access an API since you don't need to first obtain a token before you can call an API. It's basically fire and forget.

Disadvantage: compromises in security

This simplicity comes at a price.

  • The client id can easily be compromised and since it is static, a lot of damage can be done before you notice. Effectively, Swisscom assumes that anyone could hijack your client id and it's the next best thing to anonymous.

  • We cannot fine-tune your privileges on the API since there are no scopes like we have for OAuth scopes. It's a binary privilege and once you have access you can do everything, violating the principle of least privilege.

  • The client id has to be written somewhere in the App source code, so it's only halfway secure for server-to-server communication. Client id authentication in a mobile app, desktop software or browser application with Javascript (ajax) means, the client id is completely out in the public and no longer a secret.

Use cases

All this means that Client ID authentication is suited only for a handful of APIs where the following conditions are met.

  1. No confidential information is involved, and particularly: no identifiable end-customer is involved
  2. Misuse of a compromised client id has no cost impacts and/or the API client is very much aware of the sensitivity of the client id.

Examples are weather data, market information, public statements and other information that anyone has access to. Swisscom just want to know, who uses our APIs.

The immediate "competitor" of client id authentication is OAuth v2 Client Credentials. It offers the same server-to-server communication, with the added benefit that the token is routinely replaced at a given interval, using a client secret that is NOT out in the public. Hence, a compromised token can only do damage until you obtain a new one.

Using client id

The Developer provides the client id in the HTTP request, either as a request header or a query parameter in the URL. Note the exact naming of the parameter.

  • Header:

    GET /misc/v1/shops/openinghours HTTP/1.1
  Host: api.swisscom.com
  ....
  client_id: Q1H7lNJTEtBaWKb8k5cy4UrFPv03mnYC

  • Querystring: 

    GET /misc/v1/shops/openinghours?client_id=IVR89mLQOkG7PyA6Kpn5xjBZdreSbsYF

for example in a cUrl command, you would write:

curl -H "client_id:4HP1hgSwd6Iv9xpE7MClyWKsuf532oae" https://api.swisscom.com/misc/v1/shops/openinghours

or

curl https://api.swisscom.com/misc/v1/shops/openinghours?client_id=WbGN21jg5tY8RsF0XfTwydCkOuDBpEPS

or a little more elaborate in a POST:

curl -ik -H "Content-Type: application/json" -H "Accept: application/json" -X POST "https://api.swisscom.com/messaging/v1/sms" -d "{\"to\": \"%MOBILE_NUMBER_TO%_\", \"text\": \"%SMS_MESSAGE%_" }" -H "client_id:%CLIENT_ID%"

Troubleshooting

I don't have a client id, where do I get one?

There are two options.

  • You can find the API as a service in the Swisscom Application Cloud. Follow the tutorial "Where can i find clientId" to learn more.
  • You can contact us for all other APIs while we're working to get those services onto the application cloud.

Your API does not allow client id authentication

In fact, the majority of our APIs doesn't support client id authentication, due to the disadvantages mentioned earlier. The documentation of each API will tell you, which is which. Just contact us to get an equivalent OAuth v2 method of accessing the API.

My client id is apparently unknown/missing or not authorised

You get a 401 response as follows.

{
  "status": "401",
  "code": "INVALID_AUTHENTICATION_CREDENTIALS",
  "message": "Authentication credentials missing or incorrect. Check that you are using the correct authentication method and that you have permission to the given resource and your app key is approved."
}

First check that you have the correct client id and that it is activated (Swisscom application cloud: status "approved") Contact us to get a valid and approved client id and/or add the necessary authorization.

⚠️ **GitHub.com Fallback** ⚠️