KPN Encrypted Short URL API

API reference on SwaggerHub

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

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

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'

If you are using cURL for Windows, please use the command below instead.

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 authentication 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": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

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 sent to Dutch mobile phones (country code +31).

The payload uses following parameters:

  • content - Put your message here. Add the resulting URL to the message.
  • mobile_number - The mobile phone number of the addressee. Use the country code +31 at the start.
  • identifier - The data that is to be encrypted (e.g. personal data). This information will be encrypted into a token that is appended to the landing_url. The identifier can also be in the form of a URL if that URL for example contains potentially hackable data. This field is optional. If no identifier is provided, no encryption will take place and the message will be sent through as is.
  • landing_url - The URL to which the encrypted token will be appended. This should also be where the decryption part of the API is implemented. Allows only for valid URLs starting with http:// or https:// with a maximum length of 300 characters. This field is mandatory.
  • expiry_timestamp - Date and time by which the encrypted token will expire, following the format YYYY-MM-DDTHH:MM:SS in UTC+0. After this time, decryption will no longer be possible. The default value means it will virtually never expire.
  • url_shortener_key - The URL shortener key that the API will use to shorten the URL if is_short_url is set to true. This key should be obtained from RhythmOne. If no key is provided, it will default to a KPN shortener key. Allows for a maximum length of 100 characters.
  • sender - A text that should resemble the sender's origin. This string can have a maximum length of 11 characters.

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