Working with clientKey

clientKey is an identifier that you define and use to link verification sessions to your users, applications or contracts. The platform does not generate it.

With a client key you can find every session of one user, match results to your own objects such as a user, an order or a loan, filter sessions through the REST API, and process webhooks more easily.

Format

• Type: string. The raw value is at most 36 characters.
• Any string works. It is convenient to keep to Latin letters, digits and the separators _ and -.
• Do not put personal data into it. The client key stays on the session after the personal data is erased. Use an opaque identifier of your own.

Common choices: your user identifier when one check per user is enough; a combination such as user and application when the check belongs to an application, an order or a contract; or a UUID when you only want to work with the verification identifier.

Two forms: raw and encrypted

The flow:

1. On your server, take the raw client key (at most 36 characters).
2. Encrypt it with the secret key of the scenario.
3. Send the encrypted value to your page.
4. Your page passes it to window.KYCWidget.setupKYC(...) as clientKey.
5. The platform decrypts it and stores the raw value in the session.

The secret key of the scenario is shown in the scenario settings in the dashboard. It lives on your server only. Never send it to a browser, and never print it.

The encryption

The algorithm, which the samples implement:

1. Compute the SHA-256 hash of the secret key and write it as lowercase hex. Take the first 32 characters of that hex string as the AES key.
2. Generate a random 16-byte initialization vector.
3. Encrypt the raw client key with AES-256 in CBC mode with standard padding.
4. Concatenate the initialization vector and the ciphertext, and encode the result as Base64. That string is the clientKey for the widget.

Because the vector is random, the same input gives a different string each time. That is normal.

Node.js

const crypto = require("crypto");

const clientKeyRaw = "user_123";                  // at most 36 characters
const secret = process.env.SCENARIO_SECRET_KEY;   // on the server only

const key = crypto.createHash("sha256").update(secret).digest("hex").substring(0, 32);
const iv = crypto.randomBytes(16);
const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
const encrypted = Buffer.concat([cipher.update(clientKeyRaw, "utf8"), cipher.final()]);

const clientKey = Buffer.concat([iv, encrypted]).toString("base64");
// pass clientKey to the widget

Samples for Python, PHP and Go are on the integration pages: Python, PHP and Go.

Check it

The scenario settings in the dashboard have a check function: enter a test raw value and the dashboard returns the encrypted value. Use it to test the widget before your server code is ready, and confirm in the session log that the raw value you entered is what the session shows.

Common problems

• The widget reports that decryption failed. The widget received an unencrypted value, or the encryption used a different secret key than the scenario, or the value was cut when it was copied. Pass exactly the Base64 string your server produced, and check that the secret key is the one of the same scenario.
• How do I decrypt a webhook? You do not need the client key. The webhook body is encrypted with the key you set in the callback settings, not with the client key. After decryption, clientKey is one of the fields, and it holds the raw value. See webhooks.
• Each test webhook has a different encrypted string. The vector is random, so the ciphertext differs. After decryption the content is the same.

Recommended flow

1. On the server, when the verification starts, choose the raw client key, encrypt it, and store the raw value with your user or order.
2. Pass the encrypted value to the page and open the widget.
3. To read the result, accept the webhook and read clientKey from its body, or call filter sessions with the raw value.