# 🚀 Getting started

Every new client will receive a dedicated **Technical Sales Engineer (TSE)** 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**.

## 🛡️ IP whitelisting

For advanced security reasons, we use an IP whitelisting mechanism to access the API. We will take care of whitelisting any IP 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.

## 🔗 Base URLs

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.

## Authentication

This 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.

## Headers

| Header | Value |
|  --- | --- |
| `Authorization` | `HMAC <API_KEY>:<SIGNATURE>` |
| `Content-Length` | The byte length of the request body |


## Signature Calculation

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

1. **Content Length**: The length of the request body (or "0" if empty).
2. **HTTP Method**: (e.g., `GET`, `POST`, `PATCH`).
3. **Normalized URL**: The full URL, converted to lowercase, with the `?` removed.


### JavaScript Example

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


```javascript
const msg = `${contentLength || 0}${method}${url.replace("?", "").toLowerCase()}`;
const hmac = CryptoJS.HmacSHA256(msg, apiSecret);
const signature = CryptoJS.enc.Base64.stringify(hmac);
const authHeader = `HMAC ${apiKey}:${signature}`;
```