Sign in

Integrating with Privacy Services

Environments

These are the URLs to our two main applications:

Privacy Services APIs

Environment URL
Sandbox https://sandbox.api.telia.io
Production https://api.telia.io

Developer Self Service

Environment URL
Sandbox https://console.sandbox.login.telia.io
Production https://console.login.telia.io 

Setting up your client and project structure

The first step to get started with your integration is to get access to our Developer Self Service application. During the implementation phase of your application you should use our sandbox environment. Once your implementation is complete and tested you must configure your project for using our production environment

You will need to onboard yourself as a user of our Developer Self Service:

Environment URL
Sandbox https://console.sandbox.login.telia.io
Production https://console.login.telia.io 

Self-service is a very powerful tool that could potentially make the integration for all your company clients stop working so always be very selective in whom and how many people should gain access to the Developer Self Service application for your company.

Once you have gained access to the Developer Self Service, you may create clients and configure projects for your applications and services.

Calling the Privacy APIs in only three steps:

  • Get your OAuth 2.0 credentials
  • Get an access token
  • Call the API

1. Get your OAuth 2.0 credentials

Go to Developer Self Service to create an account and register your application(s). Create a client that you will use to authenticate against our APIs. It is recommended to have one client per application (web, Android, iOS, backend) due to separation of concerns. Add your client(s) to a project that will be the umbrella for all your privacy configuration.

Remember to make a note of your clientId and clientSecret.

Your client secret is confidential

While the clientId is considered public information, the clientSecret must be kept confidential. If anyone can access your clientSecret they can issue tokens and access resources they shouldn't.

2. Get an access token

Before you can access our APIs you’ll need to obtain an access token.

With Client Credentials Grant (defined in RFC 6749, section 4.4) a server client (a CLI, a daemon, or a service running on your backend), can directly ask our authorization server for an access_token, by using its Client Credentials (Client Id and Client Secret) to authenticate. In this case the token represents the server client, instead of an end user.

illustration

  • The application authenticates with our authorization server using its clientId and clientSecret.
  • The authorization server validates this information and returns an access_token.
  • The application can use the access_token to call the API on behalf of itself.

Curl

curl -s -X POST \
-d 'grant_type=client_credentials' \
-d 'client_id=<clientId>' \
-d 'client_secret=<clientSecret>' \
'https://sandbox.login.telia.io/realms/telia/protocol/openid-connect/token'

Javascript

var request = require("request");

var options = { method: 'POST',
  url: 'https://sandbox.login.telia.io/realms/telia/protocol/openid-connect/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { grant_type: 'client_credentials',
     client_id: '<clientId>',
     client_secret: '<clientSecret>'
   }
 };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Where:

  • grant_type: This must be client_credentials.
  • client_id: Your application's clientId. You can find your clientId in SelfService.
  • client_secret: Your application's clientSecret. You get the secret when you create your application in SelfService. You may regenerate your secret, but be aware that integrations that use the old secret will stop working.

The response contains a signed JSON Web Token, the token's type (which is Bearer), and how long it is until it expires in seconds.

{
  "access_token": "eyJhbGciOi....44FJrQPA",
  "expires_in": 60,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGci....17OqD7ZA",
  "token_type": "bearer",
  "id_token": "eyJhbGc....JnchX09ReQ",
  "not-before-policy": 0,
  "session_state": "d718bef2-062e-4998-bdf1-7fcb9529c534"
}

If you decode the access_token you will see that it contains among others the following claims:

{
  "iss": "https://sandbox.login.telia.io/realms/telia",
  "sub": "YOUR_USER_ID",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1489715431, // unix timestamp of the token's expiration date,
  "iat": 1489679431, // unix timestamp of the token's creation date
}

3. Call the API

Use the access_token you received in the previous step to authenticate against the Privacy APIs. Remember to replace {projectId} with YOUR project ID in the path.

Curl

curl --request GET \
  --url 'https://sandbox.api.telia.io/privacy/v2/projects/{projectId}/configurations/projectInfo' \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json'

Javascript

var request = require("request");

var options = { method: 'GET',
  url: 'https://sandbox.api.telia.io/privacy/v2/projects/{projectId}/configurations/projectInfo',
  headers:
   { authorization: 'Bearer <access_token>,
     'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Configuring privacy settings for your application

The privacy services APIs are centred around the concept of Projects. A project needs to define some basic privacy related metadata, such as your service name and other configuration. All our privacy APIs require a project ID.