NAV Navbar
shell python javascript
  • Introduction
  • Quick Start
  • Authentication
  • Transformation API
  • Daemon-Mode or Standalone API Usage
  • Advanced REST API Usage
  • Releases
  • Frequently Asked Questions (FAQ)
  • Errors
  • Introduction

    Welcome to the KIProtect API! Our Pseudonymization API allows you to easily pseudonymize sensitive data.

    We have language bindings in Shell, Python and Javascript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Quick Start

    Want to dive in? Follow these steps!

    Or, keep browsing the documentation!

    Authentication

    To send a request to the API with your token, send it as a header argument using Authorization: Bearer YOUR_TOKEN_HERE.

    # With POST 
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" -X POST https://api.kiprotect.com/psuedonymize
    
    # or use GET
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" https://api.kiprotect.com/v1/psuedonymize
    
    import requests
    
    data = requests.get('https://api.kiprotect.com/v1/transform',
                        headers={
                            'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/transform'
        method: 'GET',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    Make sure to replace YOUR_TOKEN_HERE with your API access token.

    To sign up for a developer token, please visit our sign up page. Your token should be kept private and only shared with trusted individuals (i.e. one token for team use). The token will be utilized on all requests to the APIs and will be used to track your usage with regard to request limits per day.

    To find out more about available API plans, please see our our Usage Plans.

    Transformation API

    Our transformation API is the preferred method to pseudonymize and depseudonymize your datasets. It allows you to set up a consistent configuration and enables you to send multiple messages or records to pseudonymize as a batch operation.

    In your configuration files, you can choose your pseudonymization method, data types and also provide some validity checks via formats. Curious to learn what is recommended for your specific implementation? Check out our Frequently Asked Questions (FAQ) section.

    Transform POST Request: Pseudonymization

    To use the transformation API, you will need to set up a configuration file or data structure which enables you to setup the configuration for the pseudonymization and de-pseudonymization methods. This configuration will allow you to specify what fields to pseudonymize using specific methods and data types. Please see our list of available methods and data types. By specifying a method and data type, you can best preserve utility and structure of the data while still preserving privacy.

    To the right, is an example configuration specifying a single pseudonymization operation that uses the "merengue" method (which operates on byte-strings). In the transformation definition, you can see several other transformation configuration parameters.

    The JSON also contains three items that should be pseudonymized in a list with key items.

    Start by saving this JSON object to a new file called example-config.json

    /* This is the example-config.json definition */
    
    {
        "actions": [
            {
                "name": "pseudonymize-foo",
                "transform-value" : {
                    "key": "foo",
                    "pseudonymize" : {
                        "method": "merengue",
                        "key": "<insert key or secret>", 
                    }
                }
            }
        ],
    
        "items": [
            {
                "foo": "bar"
            },
            {
                "foo": "buz"
            },
            {
                "foo": "baasdasdad"
            }
        ]
    }
    

    For the rest of the documentation, we will refer to this JSON object as example-config.json. Feel free to save this JSON to file with that name to experiment with the API.

    For each POST Request to the API, we require the following parameters:

    For a full description of what actions are available, please see Action Definition section. We also have a full listing of available configuration in the Action Configuration section.

    Submit the example-config.json file using Python, curl or Node (or your favorite language which allows for simple post requests).

    import json
    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/transform', 
                json = json.load('example-config.json'),
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -X POST https://api.kiprotect.com/api/v1/transform \ 
    --data "$(< example-config.json)" 
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/transform'
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
        body: /* here you would specify your example-config.json structure */
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    The above command returns a JSON response with the pseudonymized items like this:

    {
        "items": [
            {
                "foo": "1Gpu"
            },
            {
                "foo": "1N7y"
            },
            {
                "foo": "1Gr1enq3mCHtvw=="
            }
        ],
        "params": {
            "pseudonymize-foo": {
                "key": "t6zGXSgucvlxlLuA7Mx+LLqnxT46ww96u020PaEeYwI="
            }
        }
    }
    

    Please note the pseudonymized values have been base64-encoded, as the Merengue pseudonymizer produces byte sequences.

    In addition to the output values, the response contains a "params" JSON object, which contains the parameters of all the actions performed (in this case, a randomly generated pseudonymization key used by the "merengue" pseudonymizer). If we want to revert the pseudonymization later, we will need to store these parameters (or you can store the entire params object) and submit it again with the depseudonymization request.

    HTTP Request

    POST http://api.kiprotect.com/v1/transform

    Action Definition

    For each action in the actions JSON list, you need to set a name, and then define the action you are calling. The current available actions are: transform-value. Once you have defined the available action as a key, its value should be set to the specific configuration.

    Parameter Required Default Value Description
    name true none A unique string for this particular action (i.e. within one configuration, each action should have a unique string).
    action type true none The type of action to perform on the data. Currently, the only available type is transform-value which allows you to identify the JSON key and transform the value matching that key.

    Action Configuration

    Each action has its own configuration object which specifies how to identify the field in the passed data as well as what type of action it is (i.e. pseudonymization or depseudonymization). The transformation name is then utilized to send additional configuration details to the transformer itself. For example, when pseudonymizing a value, you will need to send a secret, which is utilized by the pseudonymization process.

    Parameter Required Default Value Description
    key true none The key from the data input that you wish to perform the action on.
    true none
    transformation name true none The name of the transformation you would like to perform. Available transformations are encode, decode, pseudonymize and depseudonymize.

    Depending on the transformation, you will have different configuration values available to your

    Transformation Configuration

    Each transformation has its own parameters available, which define the data types, pseudonymization methods and format for that particular action. They are contained in a JSON object which is nested in the action configuration as the value for the transformation name.

    Parameter Used with transformations Default Value Description
    key pseudonymize, depseudonymize none A key to use for the pseudonymization method
    method pseudonymize, depseudonymize none What is the pseudonymization method to use. Read more in our FAQ section.
    type pseudonymize, depseudonymize (only structured) none What is the data type to use. Read more in our FAQ section.
    prefixPreserving pseudonymize, depseudonymize (only structured) false If set to true, the structured data will allow the pseudonymized data to retain the same prefix shape. This means things like date strings or IP address can retain some of the same relationships as the original data (i.e. years are pseudonymized to the same new year or IP prefixes are pseudonymized to the same new prefix)
    typeParams pseudonymize, despeudonymize (only structured) none Special parameters specified to set valid values. See the supported type parameters.

    Transform POST Request: Depseudonymization

    To de-pseudonymize data, the process is similar to our initial pseudonymization transformation request. We can define a configuration and send along the items. Depending on the pseudonymization methods we used in our initial request, we may also need to additionally prepare the data.

    For example, in our initial merengue pseudonymization request, we received base64-encoded strings as the response. This is because the merengue method always returns base64-encoded strings. So, if we wanted to depseudonymize the items returned from this request, we need to define a transformation that first decodes the base64-encoded strings, then depseudonymizes them using the "merengue" pseudonymizer and finally encodes the resulting byte-string as a UTF-8 value.

    In addition, as discussed above, we pass the original params object which was produced by the merengue method during the pseudonymization process.

    We can save this config into a file example-config-depseudonymize.json and submit it via curl, Python or javascript.

    /* This is the example-config-depseudonymize.json definition */
    
    {
        "actions": [
            {
                "name": "decode-foo",
                "transform-value": {
                    "key": "foo",
                    "decode": {
                        "format": "base64"
                    }
                }
            },
            {
                "name": "depseudonymize-foo",
                "transform-value": {
                    "key": "foo",
                    "depseudonymize": {
                        "method": "merengue"
                    }
                }
            },
            {
                "name": "encode-foo",
                "transform-value": {
                    "key": "foo",
                    "encode": {
                        "format": "utf-8"
                    }
                }
            }
        ],
        "items": [
            {
                "foo": "btiM"
            },
            {
                "foo": "bhyL"
            },
            {
                "foo": "btjB64YXHiTz2A=="
            }
        ],
        "params": {
            "depseudonymize-foo": {
                "key": "oljHJOLtQo0Xy0fvi1H6adUtue0KkUVjti4JChQOhFQ="
            }
        }
    }
    

    Submit the request using a language of your choice.

    import json
    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/transform', 
                json = json.load('example-config-depseudonymize.json'),
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -X POST http://api.kiprotect.com/api/v1/transform \ 
    --data "$(< example-config-depseudonymize.json)" 
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/transform'
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' },
        body: /* here you would specify your example-config-depseudonymize.json structure */
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    The response should then look as follows:

    {
        "items": [
            {
                "foo": "bar"
            },
            {
                "foo": "buz"
            },
            {
                "foo": "baasdasdad"
            }
        ],
        "params": {
            "pseudonymize-foo": {
                "key": "oljHJOLtQo0Xy0fvi1H6adUtue0KkUVjti4JChQOhFQ="
            }
        }
    }
    

    As you can see, by chaining actions on a particular field, you can optimize your pipeline or stream by offloading the encoding and decoding into the transformation call. Our transform endpoint has been optimized to be able to process hundreds of thousands of requests a second on a single core, making it a lightweight, performant and easy-to-integrate endpoint in your larger data processing workflow or pipeline.

    If you have additional questions about how to use the transformation API or want to investigate our implemented methods and data types, please reference our Frequently Asked Questions.

    Transform POST Request: Structured Pseudonymization

    For transforming structured data points, you must first determine if your required data type is supported. If not, feel free to reach out and let us know what you need.

    Once you have found the type you'd like to use, please check to see if there are any special formatting strings available so you can more specifically define the valid values of your data. You might also want to check if there are any additional type parameters which can give you flexibility over specifying valid ranges.

    We will start with a new example of the transformation API which utilizes both structured and meregue methods with new data types.

    First, you will need to save this file as a new file named structured-pseudonymization-example.json.

    {
        "actions": [
            {
                "name": "pseudonymize-created-at",
                "transform-value" : {
                    "key": "created-at",
                    "pseudonymize" : {
                        "method": "structured",
                        "key": "my-secret-value", 
                        "type": "date",
                        "format": "%(2000-2020)Y-%m-%d"
                    }
                }
            },
            {
                "name": "pseudonymize-ip",
                "transform-value" : {
                    "key": "ip",
                    "pseudonymize" : {
                        "method": "structured",
                        "key": "another-secret-value", 
                        "type": "ip",
                        "prefixPreserving": "true"
                    }
                }
            },
            {
                "name": "pseudonymize-description",
                "transform-value" : {
                    "key": "description",
                    "pseudonymize" : {
                        "method": "merengue",
                        "key": "my-super-secret-value"
                    }
                }
            }
        ],
    
        "items": [
            {
                "created-at": "2018-09-14",
                "type" : "flow",
                "ip" : "167.41.145.0/24",
                "description" : "access-token: 23413262342112378673458243"
            },
            {
                "type": "flow",
                "created-at" : "2019-01-01",
                "ip" : "168.41.145.31",
                "description": "sensitive-information-here"
            },
            {
                "type": "flow",
                "created-at" : "2020-04-06",
                "ip" : "167.43.148.31",
                "description" : "credit-card: 3455-2662-1267-2173-3532"
            }
        ]
    }
    

    Now, let's use this new file to send to the API for pseudonymization.

    import json
    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/transform', 
                json = json.load('structured-pseudonymization-example.json'),
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -X POST https://api.kiprotect.com/api/v1/transform \ 
    --data "$(< structured-pseudonymization-example.json)" 
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/transform'
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
        body: /* here you would specify your structured-pseudonymization-example.json object */
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    The API response is as follows.

    {
        "items": [
            {
                "created-at": "2010-11-28",
                "description": "Ebl9rKAxpXJjjQVF+Krfu3nPqeNfAwONpb3mgw6gO9cqfkANGndmzw==",
                "ip": "60.56.5.0/24",
                "type": "flow"
            },
            {
                "created-at": "2013-03-18",
                "description": "M0SGx6TokCR9nXULB9QQB0tX3PUyWgMmmfA=",
                "ip": "231.239.136.32",
                "type": "flow"
            },
            {
                "created-at": "2004-03-18",
                "description": "Q+pSp5bMiDIk8QEtTj91NdfROK9rNeSEcdYh1jBCuhiHGmM6BQ==",
                "ip": "60.18.44.157",
                "type": "flow"
            }
        ],
        "params": {
            "pseudonymize-created-at": {
                "key": "viLLrpwVhce2GpL9t1r9ELq9U1+5sxf5CsmpyoltAtc="
            },
            "pseudonymize-description": {
                "key": "h59vsiVtpdXhXTHuBrRFbKov799K8E6f0/ED/ccrZ0c="
            },
            "pseudonymize-ip": {
                "key": "xqImNQNsZjB7nFY+EloWnI3UtKiogBQ/qO1ySKvQ3pU="
            }
        }
    }
    

    You will notice when setting prefixPreserving to true, the IP addresses retain the same initial prefix when pseudonymized. The pseudonymized IPs also retain the same subnet mask (from the original IP address). You will also notice the use of the formatted date string to keep the range of years between 2000-2020.

    Feel free to play around with the request and change the keys, or apply prefixPreserving to the year entries as well. You can also try IPv6 addresses or integers.

    Transform POST Request: Structured Depseudonymization

    To despeudonymize the structured data, we will make a new action list and JSON data to send. The methods will be much the same as our initial transformation request. In this example, we will send the keys rather than the parameters, to show another method of depseudonymization.

    Please save the following JSON to a new file structured-depseudonymization-example.json.

    {
        "actions": [
            {
                "name": "depseudonymize-created-at",
                "transform-value" : {
                    "key": "created-at",
                    "depseudonymize" : {
                        "method": "structured",
                        "key": "my-secret-value", 
                        "type": "date",
                        "format": "%(2000-2020)Y-%m-%d"
                    }
                }
            },
            {
                "name": "depseudonymize-ip",
                "transform-value" : {
                    "key": "ip",
                    "depseudonymize" : {
                        "method": "structured",
                        "key": "another-secret-value", 
                        "type": "ip"
                    }
                }
            },
            {
                "name": "decode-description",
                "transform-value": {
                    "key": "description",
                    "decode": {
                        "format": "base64"
                    }
                }
            },
            {
                "name": "depseudonymize-description",
                "transform-value" : {
                    "key": "description",
                    "depseudonymize" : {
                        "method": "merengue"
                        "key": "my-super-secret-value"
                    }
                }
            },
            {
                "name": "encode-description",
                "transform-value": {
                    "key": "description",
                    "encode": {
                        "format": "utf-8"
                    }
                }
            }
    
        ],
        "items": [
            {
                "created-at": "2010-11-28",
                "description": "Ebl9rKAxpXJjjQVF+Krfu3nPqeNfAwONpb3mgw6gO9cqfkANGndmzw==",
                "ip": "60.56.5.0/24",
                "type": "flow"
            },
            {
                "created-at": "2013-03-18",
                "description": "M0SGx6TokCR9nXULB9QQB0tX3PUyWgMmmfA=",
                "ip": "231.239.136.32",
                "type": "flow"
            },
            {
                "created-at": "2004-03-18",
                "description": "Q+pSp5bMiDIk8QEtTj91NdfROK9rNeSEcdYh1jBCuhiHGmM6BQ==",
                "ip": "60.18.44.157",
                "type": "flow"
            }
        ]
    }
    

    Now that you have your new configuration, you can call the API to despeudonymize with your new transformation.

    import json
    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/transform', 
                json = json.load('structured-depseudonymization-example.json'),
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -X POST http://api.kiprotect.com/api/v1/transform \ 
    --data "$(< structured-depseudonymization-example.json)" 
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/transform'
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' },
        body: /* here you would specify your structured-depseudonymization-example.json object */
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    After running the depseudonymization method in your language of choice, you should see the following output:

    {
        "items": [
            {
                "created-at": "2018-09-14",
                "description": "access-token: 23413262342112378673458243",
                "ip": "167.41.145.0/24",
                "type": "flow"
            },
            {
                "created-at": "2019-01-01",
                "description": "sensitive-information-here",
                "ip": "168.41.145.31",
                "type": "flow"
            },
            {
                "created-at": "2020-04-06",
                "description": "credit-card: 3455-2662-1267-2173-3532",
                "ip": "167.43.148.31",
                "type": "flow"
            }
        ],
        "params": {
            "decode-description": null,
            "encode-description": null,
            "depseudonymize-created-at": {
                "key": "viLLrpwVhce2GpL9t1r9ELq9U1+5sxf5CsmpyoltAtc="
            },
            "depseudonymize-description": {
                "key": "h59vsiVtpdXhXTHuBrRFbKov799K8E6f0/ED/ccrZ0c="
            },
            "depseudonymize-ip": {
                "key": "xqImNQNsZjB7nFY+EloWnI3UtKiogBQ/qO1ySKvQ3pU="
            }
        }
    }
    

    So we were able to recover our data using either the params sent back by the original request or using the same keys as arguments in the depseudonymization method.

    We hope you have enjoyed your first steps with our API. We look forward to hearing more from you and stay tuned for even more features, data types and product announcements.

    Setting Data Type Formats and Valid Values

    For more complex data types, such as dates, we offer formatting which allows you to send along the input format as well as acceptable pseudonymization outputs. For example, let's say you want to pseudonymize date strings, but you need to ensure the dates are no longer then 12 months in the future from today. You can specify both the parsing format of you date string, but also what values are valid for each part of the date string.

    To do so, your formatting string might look like the following:

    '%Y(2000-2018)-%d-%m'

    This format is sent to the API as an additional GET or POST parameter called format.

    Supported formats

    data type example description
    date '%(1950-2018)Y-%d-%(1-4)m %(08-12)H:%M:%S' a datetime or date string utilizing strftime format and allowing valid ranges of values to be passed as additional data (in parenthesis directly after the formatted value).

    Setting Type Parameters for Valid Values

    For some structured types, we support using type parameters, which can specify things like valid value ranges. For example, if you need an integer but it must be between 0 and 1000, you can specify that directly in the pseudonymization and depseudonymization parameters.

    The transformation action using typeParams would look as follows.

    {
        "actions": [
        {
            "name": "pseudonymize-n",
            "transform-value" : {
                "key": "n",
                "pseudonymize" : {
                    "method": "structured",
                    "key": "my-secret-value", 
                    "format": "raw",
                    "type": "integer",
                    "typeParams" : {
                        "min" : 0,
                        "max" : 1000
                    }
                }
            }
        }],
        "items": [
        {
            "n": 100,
            "y": "initial test"
        },
        {
            "n": 400,
            "y": "secondary test"
        },
        {
            "n": 23,
            "y": "additional test"
        }]
    }
    

    In the result n is pseudonymized to a new value between 0 and 1000.

    Supported type parameters

    data type key description
    integer 'min' The minimum value allowed after pseudonymization.
    integer 'max' The maximum value allowed after pseudonymization.

    Daemon-Mode or Standalone API Usage

    For our premium packages, we offer a standalone or daemon mode which allows you to run the KIProtect API on a server. When running in daemon mode, the KIProtect API will read from a YAML configuration file which outlines which stream or input to ingest, the fields to transform and what outputs to write or send the downstream data.

    Here, we show a simple configuration for producing "safe to share" error logs from a running application. The configuration removes sensitive information such as usernames, application IDs and IP addresses. It then writes the secure data to a new file, which you can safely share with others (presuming you have identified all necessary fields to pseudonymize).

    The configuration file is structured in an easy to use YAML file, like this one.

    input:
      type: file
      path: /var/log/my_app/errors.json
      format: json
      chunk-size: 4
      headers:
        stream: app_errors
    
    outputs:
     file:
       type: file
       path: /var/log/my_app/
       name-key: safe_to_share_errors
       format: json
       compress: false
       add-time: true 
    
    controller:
      type: default
    
      config:
        app_errors:
          actions:
            - name: pseudonymize-name
              transform-value:
                key: username
                pseudonymize:
                  method: merengue
            - name: pseudonymize-ip
              transform-value:
                key: ip_addr
                pseudonymize:
                  method: structured
                  type: ip
                  preservePrefix: true
            - name: psuedonymize-app-id
              transform-value:
                key: app_id
                pseudonymize:
                  method: structured
                  type: integer
                  typeParams:
                    min: 10000
                    max: 99999
    

    To begin consumption, there is a command to start the daemon. You can set the config via command line or leave it in the default configuration folder. The daemon will parse all available configurations before beginning.

    pseudo-daemon --config config/app_error_config.yml
    

    Kafka Integration

    We support integration with Kafka queues, allowing you to consume and write according to broker and topics. We have a keep-alive configuration parameter which will utilize polling to keep the connection alive as long as the process is running.

    At present, the Kafka consumer will grab messages until it reaches the chunk-size and then send them to be processed. Currently, the Kafka consumer expects messages to contain one element to pseudonymize. If you require consumption of large messages or processing of a different data type, please reach out.

    Here, we show a simple configuration for producing downstream events for a potential partner queue. The configuration removes sensitive information such as usernames and IP addresses. It then writes the secure data to a new topic, which can be safely shared with others (presuming you have identified all necessary fields to pseudonymize).

    Here is an example configuration file for a Kafka broker and consumer.

    
    input:
      type: kafka
      broker: localhost:9092
      chunk-size: 100
      keep-alive: true
      group: eventstream
      topics:
        - users
        - errors
      headers:
        stream: kafka_events
    
    outputs:
      kafka:
        type: kafka
        broker: localhost:9092
        keep-alive: true
        topic: partner_eventstream
        format: json
    
    controller:
      type: default
    
      config:
        kafka_events:
          actions:
            - name: pseudonymize-name
              transform-value:
                key: username
                pseudonymize:
                  method: merengue
            - name: pseudonymize-ip
              transform-value:
                key: ip_addr
                pseudonymize:
                  method: structured
                  type: ip
                  preservePrefix: true
    

    To begin consumption, there is a command to start the daemon. You can set the config via command line or leave it in the default configuration folder. The daemon will parse all available configurations before beginning.

    pseudo-daemon --config config/kafka_events_config.yml
    

    Advanced REST API Usage

    If you'd like to more manually configure your API requests or change configuration details on a message-by-message basis, we allow you to directly interface with some of our internal API endpoints.

    Pseudonymization

    Our pseudonymization API gives you the ability to choose your data types and also provide some validity checks via formats. Curious to learn what is recommended for your specific implementation? Check out our Frequently Asked Questions (FAQ) section.

    For all requests to the pseudonymization API, you will need to send a key or secret, which is a string you should keep secure and private. This key will be utilized during the pseudonymization process (and can be used with the depseudonymization API as well).

    Advanced Pseudonymization API POST Request Requirements

    For each POST Request to the API, we require the following parameters:

    Then, within the body you need to send the value you'd like to pseudonymize. You may send multiple values separated by a newline character.

    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/pseudonymize', 
                params = {'key': 'YOUR_KEY_HERE',
                          'method': 'merengue'},
                data = '123-456-789',
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -X POST "https://api.kiprotect.com/v1/pseudonymize?key=YOUR_KEY_HERE\
    &method=merengue" \ 
    --data "123-456-789"
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/psuedonymize?key=YOUR_KEY_HERE&value=123-456-789'
        method: 'POST',
        form:'123-456-789',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' }
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    The above command returns a plain-text response with the pseudonymized value like this:

    V\xf6Nu0\xb6O\xb8\xd4\xed\xa1
    

    HTTP Request

    GET http://api.kiprotect.com/v1/pseudonymize

    Query Parameters

    Parameter Required Default Value Description
    key true none Your pseudonymization key or secret
    value true none The value you wish to pseudonymize
    method false none What is the pseudonymization method to use. Read more in our FAQ section.
    type false none What is the data type to use. Read more in our FAQ section.
    format false none A format option when using the structured method from the supported formats.

    Advanced Pseudonymization API Structured Pseudonymization

    To use the structured API endpoint, which supports different data types. You can pass in the structured method and define the format argument.

    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/pseudonymize',
                params = {'key': 'YOUR_KEY_HERE',
                          'type': 'date',
                          'method': 'structured',
                          'inputformat': 'raw',
                          'outputformat': 'raw',
                          'format': '%(2008-2017)Y-%d-%m'},
                data = '2016-28-02\n2016-04-04',
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE"\
    -X POST "https://api.kiprotect.com/v1/pseudonymize?key=YOUR_KEY_HERE\
    &type=date\
    &method=structured\
    &inputformat=raw\
    &outputformat=raw\
    &format=%25(2008-2017)Y-%25d-%25m" --data $'2016-28-02\n2016-04-04'
    
    /* Utilizing the node request library */
    
    var request = require('request');
    
    request.post({url: 'https://api.kiprotect.com/v1/pseudonymize',
                  qs: {'key': 'YOUR_KEY_HERE',
                        'type': 'date',
                        'method': 'structured',
                        'inputformat': 'raw',
                        'outputformat': 'raw',
                        'format': '%(2008-2017)Y-%d-%m'}, 
                  headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' },
                  form:'2016-28-02\n2016-04-04'},
        function(err,httpResponse,body) {
           /* Parsing here */
        }
    );
    

    The above command returns a plain-text response with the pseudonymized value (or set of values separated by a newline), like this:

    2015-22-02
    2015-08-09
    

    De-Pseudonymization

    Our de-pseudonymization API enables the ability to de-pseudonymize data you pseudonymized via our API. With the pseudonymized value, your API token and pseudonymization key, you can uncover the original values.

    Basic POST Request Requirements

    For each POST Request to the API, we require the following parameters:

    Then, you can send the value in your POST request body. You may include more than one value separated by newlines (and this will be sent back to you with newline separators).

    import requests
    
    data = requests.get('https://api.kiprotect.com/v1/depseudonymize', 
                params = {'key': 'YOUR_KEY_HERE',
                          'method': 'merengue'},
                data = '234-567-890',
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -X POST "https://api.kiprotect.com/v1/depseudonymize?\
    key=YOUR_KEY_HERE&method=merengue" \
    --data $'234-567-890'
    
    
    const https = require('https');
    
    var options = {
        host: 'api.kiprotect.com',
        port: 443,
        path: '/depsuedonymize?key=YOUR_KEY_HERE&method=merengue',
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' },
        form:'234-567-890'
    };
    
    https.request(options, (resp) => {
       /* Parsing here */
    });
    
    

    The above command returns a plain-text response with the pseudonymized value like this:

    123-456-789
    

    HTTP Request

    GET http://api.kiprotect.com/v1/depseudonymize

    Query Parameters

    Parameter Required Default Value Description
    key true none Your pseudonymization key or secret
    value true none The value you wish to pseudonymize
    method false none What is the pseudonymization method to use. Read more in our FAQ section.
    type false none What is the data type to use. Read more in our FAQ section.
    inputformat false raw What input format you are sending. Choices are: raw, base64, base64-url
    outputformat false raw What output format you are sending. Choices are: raw, base64, base64-url
    format false none A format option from the supported formats.

    Basic POST Request Requirements

    For each POST Request to the API, we require the same information as in the GET requests. The value (or values), however, can be sent via POST for increased security. This also allows you to post multiple values to be depseudonymized at the same time.

    import requests
    
    data = requests.post('https://api.kiprotect.com/v1/depseudonymize',
                params = {'key': 'YOUR_KEY_HERE',
                          'type': 'date',
                          'method': 'structured',
                          'inputformat': 'raw',
                          'outputformat': 'raw', 
                          'format': '%(2008-2017)Y-%d-%m'},
                data = '2015-22-02\n2015-08-09'
                headers = {'Authorization': 'Bearer YOUR_TOKEN_HERE'})
    
    
    curl -H "Authorization: Bearer YOUR_TOKEN_HERE"\
    -X POST "https://api.kiprotect.com/v1/depseudonymize?key=YOUR_KEY_HERE\
    &type=date\
    &method=structured\
    &inputformat=raw\
    &outputformat=raw\
    &format=%25(2008-2017)Y-%25d-%25m" --data $'2015-22-02\n2015-08-09'
    
    /* Utilizing the node request library */
    
    var request = require('request');
    
    request.post({url: 'https://api.kiprotect.com/v1/depseudonymize,
                  qs: {'key': 'YOUR_KEY_HERE',
                        'type': 'date',
                        'method': 'structured',
                        'inputformat': 'raw',
                        'outputformat': 'raw',
                        'format': '%(2008-2017)Y-%d-%m'}, 
                  headers: { 'Authorization': 'Bearer YOUR_TOKEN_HERE' },
                  form:'2015-22-02\n2015-08-09'},
        function(err,httpResponse,body) {
           /* Parsing here */
        }
    );
    

    The above command returns a plain-text response with the pseudonymized value (or set of values separated by a newline), like this:

    2016-28-02
    2016-04-04
    

    Releases

    18 July 2018: This is the v0.1.1 release of the KIProtect Pseudonymization API. The release added two new structured pseudonymization types: IP addresses and integers. This also introduces a new configuration parameter for structured pseudonymization: type parameters.. Finally, we also added our initial Apache Kafka integration.

    22 June 2018: This is the v0.1.0 release of the KIProtect Pseudonymization API. Our release schedule is not explicitly set, but we encourage feedback and feature requests which we will integrate in future releases.

    For more information of our plans, please refer to our release schedule and product roadmap.

    Planned Future Releases

    Product Roadmap

    Our current product roadmap will cover the following new functionality and data types:

    Do you have a pseudonymization or anonymization need we don't support or have in our roadmap? We'd love to hear about it! Please let us know.

    Frequently Asked Questions (FAQ)

    About Pseudonymization, Methods and Data Types

    API Details

    Support

    Pseudonymization Methods

    We have several pseudonymization methods which allow you to specify different data types for pseudonymization. They are as follows:

    method name supported types description
    merengue Merengue Data Types The merengue method allows for pseudonymization of strings and byte arrays.
    structured Structured Data Types The structured method allows for pseudonymization of structured data and specifically aims to preserve structure in the pseudonymization process.

    Pseudonymization Data Types

    For the best results from KIProtect Pseudonymization, you should define data types for your API calls. These data types should match the input values you are using. Our data types allow you to retain some utility and structure of your data after pseudonymization.

    We have different supported data types available for the different pseudonymization methods.

    Merengue Method Data Types

    data type name | example | description string | 'testing' | a UTF-8 or base64-encoded string (Note: If using base64, you will need to specify this in the inputformat parameter. bytes | | any bytearray or bytestring

    Structured Method Data Types

    data type name example description
    integer 1234 any integer value (including bigints)
    ip 127.0.0.1 any IP Address (Internet Protocol)
    date 2017-01-30 any datetime string (format can be specified in the call)
    bytes any bytearray or bytestring

    Note that bytes will not preserve structure and validity of the data in a meaningful way. For preserving data utility, please utilize the specific data types.

    We are continuously working on new supported data types. If you need a particular structure we haven't yet implemented, please let us know your requirements.

    About Pseudonymization

    Pseudonymization is the process of taking real data and modifying it to no longer represent the original data. Common pseudonymization methods available are masking data (i.e. replacement of the data with a data type or simple representation such as XXXX), or hashing data (which leaves data as a long hash value, allowing no further utility.

    At KIProtect, we have developed a cryptographic method which allows your data to retain some of the initial structure while still modifying it to no longer represent the original values. This means you keep some data utility while protecting your data.

    Pseudonymization Requirements

    To properly pseudonymize data, we need to ensure it meets requirements of our pseudonymization methods. Primarily, the values need to be long enough to provide a proper pseudonymization scheme. If your inputs will regularly be less than 5 characters in length, pseudonymization will likely not work well for your data.

    However, if your data has varying length of 6 characters or more, our API should work well for you. If you have other questions about whether the API is a good fit for your data, feel free to reach out via email to discuss.

    API Limits

    Our free and public API allows you 10,000 requests per day. For more data throughput, please sign up for a premium plan. As far as rate limits for the API, we support up to 100 requests per second with the public API. If you need higher rates, please contact us about a premium plan.

    Key Usage

    Technically, you could pass a shared keyphrase as a key (or any string); but the method we utilize with the key benefits from increased complexity and randomness. For this reason, we recommend using a public key from a SSH Keypair. You can generate one and distribute the public key to the team who will be utilizing the API. This key will then need to be used for any de-pseudonymization requests. Need help creating a key? Check out GitHub's cross-platform instructions.

    Currently, you need to manage the keys for the API; however we are building a key management system to help alleviate sharing keys across a team.

    Hosting

    Need to host KIProtect's Pseudonymization API internally? We can offer a containerized solution for that! Contact us to learn more.

    Pseudonymization Type Missing

    Your needs might already be covered in our future releases which we might be able to offer ahead of schedule as a beta API. Interested to learn more? Feel free to reach out anytime.

    We are continously working on new data types for our Pseudonymization API and we'd love to hear your feedback on which types are most useful to you. Please let us know your needs regarding data types we can offer.

    Feature Request

    Your request might already be covered in our future releases which we might be able to offer ahead of schedule as a beta API. Interested to learn more? Feel free to reach out.

    Need a feature or integration that is not currently supported? We'd love to hear more (and we might already be working on it!). Reach out so we can hear more and let you know about availability of new features.

    Bug Reporting

    Found a bug? Let us know!

    Please include a way we can reach you via email as well as a short and long description. Do not include your API tokens or key information, but feel free to pass along any other information you can to help us reproduce the error. Thank you again for taking the time to report the issue.

    Please fill out the form below. An email address is required.

    Contact Email:

    Title (short summary):

    Full Description:

    Errors

    Errors encountered in the processing of the API request will be sent directly back to the user. The format will be sent in JSON with a message detailing the error encountered when processing.

    To note, we are actively working on a feature to better surface errors of individual fields while still allowing the non-affected transformations to be properly returned. If this is a requirement for your use of our API, please let us know.