KPN

Encrypted Short URLs - KPN

KPN

Communicate URLs securely via SMS

Easy and user-friendly encrypted URLs

  • Security

API reference on SwaggerHub API reference on Postman

Introduction

The Encrypted Short URL API helps you safely encrypt any sensitive data that you send through SMS.

The API provides you with a KPN messaging service through which you can secure messages that contain sensitive data, e.g. a URL that contains an address, id or other personal data. The API takes the sensitive data and encrypts it into a token that is then appended to a URL. The resulting URL takes the receiver of the SMS to a page on your domain where you have implemented the decryption part of the API. This part will then decrypt the token back into the original data for further use.

Conceptual Model

Conceptual model

API workflow

API workflow

Prerequisites

Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Access token: read more below under Authentication > Get Access Token for more information on how to obtain an access token.

Landing URL: you should have a URL where the receiver of your SMS goes to to decrypt the token. In other words, this is where the decryption part of the API should be implemented.

URL shortener key: if you want to use your own key, you have to obtain one from from po.st.

Constraints

Support

As of now the Encrypted Short URL API only supports SMS as a messaging channel.

The API does not support bulk SMS messages.

The max number of characters allowed per SMS is 800.

The identifier to encrypt allows up to 150 characters.

Country restriction

With this API, messages can only be send to mobile phones registered in the Netherlands. So the country code is locked to 31.

Mobile phone number

The mobile phone number should be formatted as follows:

  • Dutch mobile phone number: 0612345678 or 0031612345678 (00 + Dutch country code 31 + phone number)

Landing URL

The landing URL should be less than 300 characters.

Expiry timestamp

The expiry timestamp should conform to the ISO 8601 format with the complete date plus hours, minutes and seconds (YYYY-MM-DDTHH-MM-SS). The timezone should be UTC+0. Example: 2019-12-11T23:59:59.

URL shortener key

The URL shortener key field allows for a maximum of 100 characters.

When using your own key, the key should be obtained from po.st.

Getting started

Authentication

OAuth 2.0

For accessing and/or manipulating resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: these tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end user).

We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token among other useful information

Get access token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute the below cURL command to receive an access token.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

Note: If you are using cURL for Windows then please use the below command.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

How to...

Encrypt a URL

Send an encrypted token with url to a mobile phone number.
Note: Keep in mind that messages can only be send to Dutch mobile phones (country code +31).

Example request body:

{
  "message": {
    "mobile_number": "06xxxxxxxx",
    "content": "Please click here: {url}"
  },
  "url_details": {
    "identifier": "id=12345678",
    "landing_url": "https://www.example.com",
    "expiry_timestamp": "2019-12-11T23:59:59",
    "url_shortener_key": "",
    "sender": "KPN"
  }
}

Example response:

{
    "document_id": "3ad86db3-6d26-45cf-9002-fe1cd8940b9e",
    "status": "OK"
}

Decrypt a URL

Decrypt a given encrypted token value.

Example encrypted token:

curl -X GET ".../decrypt?token={encrypted_token_value}" -H "accept: application/json"

Example response:

{
    "identifier": "id=12345678"
}

Return codes

Code Meaning
200 Success
201 Created
202 Accepted
400 Bad request
401 Unauthorized
404 Not Found
405 Method not Allowed
412 Precondition failed
429 Too many requests
500 Internal server error
502 Bad gateway
503 Service unavailable

API versions

Version   Description
1.0.0   Initial version