Platform Encryption v0.4.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The Encryption API allows a client to fetch a public encryption key in order to encrypt secret or sensitive (such as personally identifying information) data in request payloads, so that the client does not send such data in clear text in JSON requests.

For example, consider a request body schema that has two properties username and password which are each tagged with x-apiture-encrypt: true, indicating that they should be encrypted before POSTing the data to an API service:

required:
  - username
  - password
  - encryptedWith
properties:
  username:
    description: >-
      A banking customer's login username.
    allOf:
      - $ref: '#/components/schemas/encryptedString'
    x-apiture-encrypt: true
  password:
    description: >-
      A banking customer's login password.
    allOf:
      - $ref: '#/components/schemas/encryptedString'
    x-apiture-encrypt: true
  encryptedWith:
    $ref: '#/components/schemas/encryptedWith'

(See an example in the schema sampleSensitiveRequestBody below.) Instead of passing the sensitive data in clear text such as:

{
  "username": "trilby",
  "password": "#juggle-4-sugary-mallets%"
}

the client should encrypt and encode each value when constructing the JSON request object.

To encrypt sensitive data when building a request body, the client should fetch the public encryption key via 'getPublicEncryptionKey' to obtain a recent (unexpired) publicEncryptionKey object.

Next, the client should generate an array of random salt bytes and concatenate the random salt with the clear text data to be encrypted. Salted data helps ensure better encryption of short data strings. The 'getPublicEncryptionKey' response includes a saltLength integer property which is the number of salt bytes to prepend to the clear text.

The response from getPublicEncryptionKey includes an id and a publicKey for the public encryption key. The client should use the publicKey to encrypt the data. A web client may use SubtleCrypto. Note SubtleCrypto requires the web client to be running in a secure context, such as a web page at an https URL. Non-browser/non-mobile Node.js clients may use the crypto package.

After encrypting the data, the client should Base64 encode the encrypted byte sequence so that the value can be embedded as an ASCII string in a JSON request object.

When passing encrypted data, the client also passes a sibling encryptedWith property. The encryptedWith property is the id of the publicEncryptionKey object.

In the continued example below, let "username-encrypted-with-public-key" represent the encrypted and Base64 encoded username value, which was encrypted using the public key instance with id value 'B74ae2504D8E'. Let "password-encrypted-with-public-key" represent the encrypted Base64 encoded password value which was encrypted using the same public key.

The client passes the encrypted and Base64 encoded values and a sibling encryptedWith string which is the id of the public key instances the client used to encrypt the encrypted properties:

{
  "username": "username-encrypted-with-public-key",
  "password": "password-encrypted-with-public-key",
  "encryptedWith": "B74ae2504D8E",
  ]
}

All data in the request should be encrypted with the same public encryption key instance.

Encryption keys are rotated and expire after a few minutes. A client may cache the public encryption key object obtained by getPublicEncryptionKey, but the client should fetch a new key at least 60 seconds before the publicEncryptionKey.expiresAt time passes to allow for latency when making and completing an API call with the encrypted data. (Note: the expiresAt timestamp is in UTC time zone.)

Download OpenAPI Definition (YAML)

Base URLs:

• https://api.apiture.com/platform

Terms of service

Email: Apiture Web: Apiture

License: Apiture API License

Authentication

• OAuth2 authentication (clientCredentials)
  • Client Credentials OAuth2 flow that allows a secure service application to access resources. (This access is not used with insecure clients such as web or mobile applications.) See details at Secure Access.
  • Flow: clientCredentials
  • Token URL = https://dev-oidc.apiture-comm-nonprod.com/oidc/token

Encryption

Public key encryption for secret or sensitive data

getPublicEncryptionKey

Code samples

# You can also use wget
curl -X GET https://api.apiture.com/platform/publicEncryptionKey \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.apiture.com/platform/publicEncryptionKey HTTP/1.1
Host: api.apiture.com
Accept: application/json

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('https://api.apiture.com/platform/publicEncryptionKey',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: 'https://api.apiture.com/platform/publicEncryptionKey',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.apiture.com/platform/publicEncryptionKey',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.apiture.com/platform/publicEncryptionKey', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.apiture.com/platform/publicEncryptionKey");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.apiture.com/platform/publicEncryptionKey", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Fetch a public encryption key.

GET https://api.apiture.com/platform/publicEncryptionKey

Fetch or create a public encryption key which allows a client to encrypt secret or sensitive data in request payloads.

This operation may return a recently returned encryption key, or if the service has needs to rotate the key, the operation creates a new key.

This operation is designed to be called from the following identity types:

• Banking customer
• Secure service client

Example responses

200 Response

{
  "id": "B74ae2504D8E",
  "expiresAt": "2025-03-09T05:09:16.375Z",
  "publicKey": "-----BEGIN RSA PUBLIC KEY----- MIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B... -----END RSA PUBLIC KEY-----"
}

Responses

Response Schema

Status Code 400

Status Code 401

Status Code 403

Status Code 429

Status Code 4XX

Status Code 5XX

Schemas

apiProblem

{
  "id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
  "type": "https://production.api.apiture.com/errors/accountNotFound/v1.0.0",
  "title": "Account Not Found",
  "status": 422,
  "occurredAt": "2022-04-25T12:42:21.375Z",
  "detail": "No account exists at the given account_url",
  "instance": "https://production.api.apiture.com/banking/transfers/bb709151-575041fcd617"
}

API Problem (v1.2.2)

API problem or error, as per RFC 7807 application/problem+json.

Properties

encryptedString

"stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstring"

Encrypted String (v1.0.0)

A string value that has been encrypted using a public encryption key then Base64 encoded.

type: string

minLength: 120
maxLength: 8096

encryptedWith

"string"

Encrypted With (v2.0.0)

The id of the public encryption key instance the client used to encrypt the data.

type: string

minLength: 6
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]{6,48}$"

problemResponse

{
  "id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
  "type": "https://production.api.apiture.com/errors/noSuchAccount/v1.0.0",
  "title": "Account Not Found",
  "status": 422,
  "occurredAt": "2022-04-25T12:42:21.375Z",
  "detail": "No account exists for the given account reference",
  "instance": "https://production.api.apiture.com/banking/transfers/bb709151-575041fcd617"
}

Problem Response (v0.4.2)

API problem or error response, as per RFC 9457 application/problem+json.

Properties

publicEncryptionKey

{
  "id": "B74ae2504D8E",
  "expiresAt": "2025-03-09T05:09:16.375Z",
  "publicKey": "-----BEGIN RSA PUBLIC KEY----- MIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B... -----END RSA PUBLIC KEY-----"
}

Public Encryption Key (v1.1.0)

Data necessary to encrypt data with a public encryption key.

Properties

publicEncryptionKeyId

"4c4fe85cf1c819d1ad15"

Public Encryption Key Id (v1.1.0)

The id of an public encryption key instance.

type: string

minLength: 6
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]{6,48}$"

readOnlyResourceId

"string"

Read-only Resource Identifier (v1.0.1)

The unique, opaque system-assigned identifier for a resource. This case-sensitive ID is also used in URLs as path parameters or in other properties or parameters that reference a resource by ID rather than URL. Resource IDs are immutable.

type: string

read-only
minLength: 6
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]{6,48}$"

readOnlyTimestamp

"2021-10-30T19:06:04.250Z"

Read-Only Timestamp (v1.0.0)

A readonly or derived timestamp (an instant in time) formatted in RFC 3339 date-time UTC format: YYYY-MM-DDThh:mm:ss.sssZ.

type: string(date-time)

read-only
format: date-time
minLength: 20
maxLength: 30

resourceId

"string"

Resource Identifier (v1.0.1)

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

type: string

minLength: 6
maxLength: 48
pattern: "^[-_:.~$a-zA-Z0-9]{6,48}$"

sampleSensitiveRequestBody

{
  "username": "MDEyMzQ1NTQzMjE+PlRoaXMgc2FtcGxlIHZhbHVlIHNob3VsZCBiZSB0aGUgQmFzZTY0IGVuY29k ZWQgdmFsdWUgb2YgdGhlIGVuY3J5cHRlZCB1c2VybmFtZS48PDAxMjM0NTU0MzIxCjAxMjM0NTU0 MzIxPj5UaGlzIHNhbXBsZWQgZGF0YSBpcyBub3QgYWN0dWFsbHkgZW5jcnlwdGVkLCBidXQgY29k ZWQgdG8gbG9vayBsaWtlIGJpbmFyeTw8MDEyMzQ1NTQzMjEKMDEyMzQ1NTQzMjE+PmRhdGEuPDww MTIzNDU1NDMyMQ==",
  "password": "MDEyMzQ1NTQzMjE+PlRoaXMgc2FtcGxlIHZhbHVlIHNob3VsZCBiZSB0aGUgQmFzZTY0IGVuY29k ZWQgdmFsdWUgb2YgdGhlIGVuY3J5cHRlZCBwYXNzd29yZC48PDAxMjM0NTU0MzIxCjAxMjM0NTU0 MzIxPj5UaGlzIHNhbXBsZWQgZGF0YSBpcyBub3QgYWN0dWFsbHkgZW5jcnlwdGVkLCBidXQgY29k ZWQgdG8gbG9vayBsaWtlIGJpbmFyeTw8MDEyMzQ1NTQzMjEKMDEyMzQ1NTQzMjE+PmRhdGEuPDww MTIzNDU1NDMyMQo=",
  "encryptedWith": "B74ae2504D8E"
}

Sample Sensitive Request Body (v1.0.0)

A sample request body which contains secret data to be encrypted. The properties username and password should be encrypted with the public encryption key returned from getPublicEncryptionKey. This request body includes the required encryptedWith property which lists the id of the encryption key that the client used to encrypt the properties.

Properties