🚀 Getting started

Every new client will receive a dedicated Client Success Manager (CSM) who will guide them through the integration and answer any question they might have – technical or otherwise.

Upon starting the onboarding, we will create a dedicated institution entity in our system to represent your organization. We will return you a unique ID for your institution, called the institutionID. It follows a digit hexadecimal code format such as: 69a1e097-d243-74d2-9545-5676eb5bed7b9

⚠️ (!) You will need your institution’s unique ID in order to call our API.

📡 We will also give you access to a dedicated API collection on Postman.

For advanced security reasons, we use an IP whitelisting mechanism to access the API. We will take care of the whitelisting of any IPs that you give us. You have several options when it comes to the IPs:

• 📍 Static IPs
• 🌐 IP ranges
• 🔗 Daily IP whitelisting link: Received automatically for fast manual testing

You can request the whitelisting of further IPs or IP ranges at any time.

In your API calls, you will need to set the variables baseUrl and baseUrlWebsites. These depend on the environment (UAT or Production), but are otherwise static:

🏗️ UAT:

• BaseUrl: https://uat.api.nyala.de

• BaseUrlWebsite: https://uat.vault.nyala.de

🌐 Production:

• BaseUrl: https://api.nyala.de

• BaseUrlWebsite: https://vault.nyala.de

They are also set and displayed in your Postman API collection.

The Customer API uses HMAC (Hash-based Message Authentication Code) for security. Every request must include an Authorization header containing a signature generated using your Secret Key.

The signature is a Base64 encoded HMAC-SHA256 hash. The "message" to be signed is constructed by concatenating the following strings in order and without separators:

1. Content Length: The length of the request body (or "0" if there is no body / empty).
2. HTTP Method: (e.g., GET, POST, PATCH).
3. Path: everything after the base URL (path and query), in lower case, with the first "?" removed. Do not include https:// or the host.

Examples:

Use /api/external/v1/status/auth to test your signature: it returns 200 only if the signature is valid.

You can use this logic in your frontend or Node.js applications:

const u = new URL(url);
const path = (u.pathname + u.search).replace("?", "").toLowerCase();
const msg = `${contentLength || 0}${method}${path}`;
const signature = CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(msg, apiSecret));
const authHeader = `HMAC ${apiKey}:${signature}`;

This is the logic the message signature works with on python:

import base64, hashlib, hmac
    path = "/api/external/v1/status/auth"            # everything after the base URL
    msg = f"{content_length}{method}{path.replace('?', '', 1).lower()}"
    digest = hmac.new(api_secret.encode(), msg.encode(), hashlib.sha256).digest()
    auth_header = f"HMAC {api_key}:{base64.b64encode(digest).decode()}"

In the Tokenization API Every request must include:

No signature is needed. Your API integration must be set up by NYALA before the Tokenization API accepts your key; your CSM confirms when this is done.

Fields with a fixed list of options take a number. Responses always return the number. The Tokenization API also accepts the name; the Customer API currently accepts numbers only for blockchain.

entryType can be empty (null) in older records.