# 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": "john.doe@example.com",
    "fields": {
      "fieldFirstName": "John",
      "fieldLastName": "Doe"
    }
  }'
```

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

### Authentication Flow

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


The API method is only executed **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**.
3. Scroll to the **Developer Key** section.
4. Store the **Developer Key** (e.g. `{{DEVELOPER_KEY}}`), which is a unique key that identifies your integration.
5. *Optional:* Update your Name in the Access Confirmation Dialog. This name is shown to customers during the authorization process.
6. Check the Link to the “Access Confirmation” dialog.
Example:

```
https://app.klicktipp.com/grantapiaccess/{{ACCOUNT_ID}}?url=
```
7. Append a redirect URL to the **Access Confirmation** link.
This URL is the endpoint in your system that will receive the customer key.
Example:

```
https://app.klicktipp.com/grantapiaccess/{{ACCOUNT_ID}}?url=https://yourdomain.com/klicktipp-api
```
8. Share this complete URL with your customer.
9. The customer opens the link and confirms API access in the dialog.
10. After clicking **Confirm API Access**, KlickTipp redirects the customer to your provided URL and automatically appends the **Customer Key** as a query parameter.
Example:

```
 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** (e.g. `{{DEVELOPER_KEY}}`) for all authenticated API requests.


### 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 KlickTipp username of the customer
- `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: {{USERNAME}}' \
  -H 'X-Ci: {{CIPHERTEXT}}' \
  -d '{
    "email": "john.doe@example.com",
    "fields": {
      "fieldFirstName": "John",
      "fieldLastName": "Doe"
    }
  }'
```

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