# How to authenticate and access the Management API

This document explains how to authenticate and access the KlickTipp API in a secure and production-ready way.

KlickTipp provides two supported authentication methods:

- **Username + Password** (session-based)
- **Developer Key + Customer Key** (key-based)


Both methods grant access to the same API backend.
There is no separate “Partner API” or “Management API” authentication layer.

**Username + Password** authentication is supported but intended mainly for internal tools, testing, or short-lived integrations.

For long-term, partner, and customer-facing integrations, **Developer Key + Customer Key is the recommended approach**, as it avoids dependency on user credentials and allows explicit customer authorization.

## Requirements

- KlickTipp **Premium** plan or higher to use the API
- **Enterprise** account to use Developer Key and Customer Key authentication
- API endpoint:



```
  https://api.klicktipp.com
```

## Step-By-Step Instructions for Username + Password

Username + Password authentication uses a **session-based login**.
It is supported by the KlickTipp API but **not recommended for long-term or partner integrations**, as password changes or user modifications can break the connection.

### Authentication Flow

1. Authenticate using **username and password**
2. KlickTipp creates a **session**
3. A **session ID** is returned
4. The session ID is sent with every API request
5. The session is explicitly terminated via logout or expires automatically


[View full API reference](/management-api#tag/authentication)

### Creating a Dedicated API User

Even when using Username + Password authentication, a **dedicated API User** must be used.
We do not recommend to use the main account for API access.

1. Log in with your main KlickTipp account
2. Go to
My Account → Settings → User Account
3. Scroll to Sub-Accounts
4. Click Create Sub-Account
5. Enter a name
The resulting username will be:
`mainaccount-subaccountname`
6. Enter an email address
This is only used for registration and notifications
7. Select the role API User
8. Click Create Sub-Account


The API User can now be used for all API authentication.

### Session Handling via Login & Logout

After a successful login, KlickTipp returns a session identifier.
This session must be included in every subsequent API request.

Best practices:

- Perform login once per process or job
- Store the session ID only temporarily
- Reuse the session for multiple API calls
- Explicitly log out when processing is complete
- Do not persist sessions long-term


### Example Request

**Example Request:**


```bash
curl -i -X POST \
  https://api.klicktipp.com/account/login \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "mainaccount-subaccountname",
    "password": "YOUR_PASSWORD"
  }'
```

**Example Response (simplified):**


```json
{
  "session_id": "SESSION_ID"
}
```

**Example Request:**


```bash
curl -i -X POST \
  https://api.klicktipp.com/subscriber \
  -H 'Content-Type: application/json' \
  -H 'X-Session-Id: SESSION_ID' \
  -d '{
    "email": "alex.example@klicktipp.example",
    "fields": {
      "fieldFirstName": "Alex",
      "fieldLastName": "Example"
    }
  }'
```

## Step‑By‑Step Instructions for Developer Key + Customer Key

### Authentication Flow

1. Developer Key (Partner / App)
2. Customer authorizes access via the KlickTipp dialog
3. Customer Key is generated and sent back to your system
4. Developer Key + Customer Key are used for every API request
5. KlickTipp validates keys and permissions


The API method is executed **only after** authentication succeeds.

### Querying the Customer Key

To obtain a **Customer Key** for a KlickTipp account, your integration must guide the customer through the API access authorization dialog.

Follow these steps:

1. Log in to your KlickTipp account.
2. Navigate to **My Account → Settings → User Account** and click on **Change personal information**.
3. Navigate to **Integrations** → **API & Apps** and see the **Developer Key** section.
4. Store the **Developer Key** (e.g. `{{DEVELOPER_KEY}}`), which uniquely identifies your integration.
5. *Optional:* Update your Name in the Access Confirmation dialog. This name is shown to customers.
6. Copy the link to the **Access Confirmation** dialog.

```
https://app.klicktipp.com/grantapiaccess/{{ACCOUNT_ID}}?url=
```
7. Append a redirect URL to the Access Confirmation link.    This URL must include `customerkey=` at the end.

```
https://app.klicktipp.com/grantapiaccess/{{ACCOUNT_ID}}?url=https://yourdomain.com/klicktipp-api?customerkey=
```
8. Provide a **Connect** button that opens the full Access Confirmation URL for the customer.
9. The customer clicks **Confirm API Access** in the KlickTipp dialog.
10. KlickTipp redirects to your URL and appends the Customer Key automatically.

```
https://yourdomain.com/klicktipp-api?customerkey={{CUSTOMER_KEY}}
```
11. Store the received **Customer Key** (`{{CUSTOMER_KEY}}`) securely and use it together with your **Developer Key** (`{{DEVELOPER_KEY}}`) for all authenticated API requests.


### Fixed Username for Partner Integrations

**Important:** In partner integrations, `X-Un` is always the fixed partner API user
(e.g. `partner_user`). The Developer Key belongs to the partner account and is therefore
global. The only customer‑specific secret is the Customer Key.

**Implementation consequences:**

- `X-Un` is hard‑coded globally (partner account username).
- The **Developer Key** is hard‑coded globally (partner account).
- Only the **Customer Key** is tenant‑specific and must be stored per installation via the described flow.
- Therefore the UI should only expose a Connect action and does not need not show any username/key inputs.


### Example Request

For partner integrations and production usage, every API request must be authenticated using the **Developer Key** and the customer’s **Customer Key**.

The two keys are **not sent directly**. Instead, they are combined into a cryptographic token (`X-Ci`) and transmitted via HTTP headers, as defined by the official KlickTipp partner connector.

**Authentication headers:**

- `X-Un` – the **fixed partner username**
- `X-Ci` – a Base64‑encoded cipher generated from
**Developer Key + Customer Key**


**Example: Create or Update Contact**


```bash
curl -i -X POST \
https://api.klicktipp.com/subscriber \
-H 'Content-Type: application/json' \
-H 'X-Un: {{PARTNER_USERNAME}}' \
-H 'X-Ci: {{CIPHERTEXT}}' \
-d '{
 "email": "alex.example@example.klicktipp",
 "fields": {
   "fieldFirstName": "Alex",
   "fieldLastName": "Example"
 }
}
```

## Summary

The KlickTipp **Management API supports two authentication methods** that provide access to the same API backend, but they are intended for different use cases.

Username + Password authentication is session-based and suitable for internal tools, testing scenarios, or short-lived integrations. It requires careful session handling and can break if user credentials change.

For production-ready, partner, and customer-facing integrations, Developer Key + Customer Key authentication is the recommended approach. It provides stable, long-term access without relying on user credentials and enables explicit customer authorization via a dedicated confirmation flow.

Robust integrations should always prefer key-based authentication, as it offers better security, clearer ownership, and predictable behavior across different customer accounts.