> For the complete documentation index, see [llms.txt](https://qpapel.papelship.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qpapel.papelship.com/documentation/tr-documentation/fonksiyonlar/validate-key.md).

# Validate Key

Validates a license key with the server and initializes an authenticated session.

{% hint style="info" %}
A secure connection must be established by calling `qpapel::Connect(ctx)` before attempting validation.
{% endhint %}

***

## Signature

```cpp
char* Authenticate(QPCTX c, const char* licenseKey);
```

***

## Parameters

| Parameter    | Type          | Description                                                 | Required |
| ------------ | ------------- | ----------------------------------------------------------- | -------- |
| `c`          | `QPCTX`       | Client context pointer                                      | Yes      |
| `licenseKey` | `const char*` | The license key to validate (Format: `XXXX-XXXX-XXXX-XXXX`) | Yes      |

***

## Returns

**Type:** `char*`

| Value            | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| `Non-null char*` | Validation succeeded. Returns the session JWT token.                 |
| `nullptr`        | Validation failed. Check `qpapel::GetLastStatus(ctx)` for the error. |

{% hint style="warning" %}
The returned session token string is dynamically allocated by the SDK. To prevent memory leaks in your application, you **must** release this memory by calling `qpapel::FreeString(sessionToken)` when you are done using it.
{% endhint %}

***

## Basic Example

```cpp
#include <iostream>
#include "qPapelLib.h"

int main() {
    if (!qpapel::Init()) return 1;
    
    QPCTX ctx = qpapel::CreateContext();
    qpapel::SetConfig(ctx, "pk_your_api_key", "", 0, "1.0.0");
    
    if (qpapel::Connect(ctx)) {
        std::string licenseKey;
        std::cout << "Enter license key: ";
        std::cin >> licenseKey;
        
        std::cout << "[Auth] Validating key..." << std::endl;
        char* token = qpapel::Authenticate(ctx, licenseKey.c_str());
        
        if (token != nullptr) {
            std::cout << "[SUCCESS] Valid license key!" << std::endl;
            std::cout << "Session Token: " << token << std::endl;
            
            // Free the allocated memory!
            qpapel::FreeString(token);
        } else {
            char* err = qpapel::GetLastStatus(ctx);
            std::cerr << "[FAILED] Error: " << (err ? err : "Invalid Key") << std::endl;
            if (err) qpapel::FreeString(err);
        }
    }
    
    qpapel::DestroyContext(ctx);
    return 0;
}
```

***

## Web Panel Key Validation Steps

When `Authenticate` is called, the server performs the following checks:

1. **Key Existence**: Verifies that the key exists in the database.
2. **Key Status**: Confirms that the key is active (not suspended or expired).
3. **HWID Matching**: Compares the local hardware signature with the registered HWID to prevent multi-device license abuse.
4. **Device Limit**: Ensures that the maximum device count has not been exceeded.
5. **Product Access**: Validates that this key has permissions to load the requested product.

***

## Common Error Codes

Use `qpapel::GetLastStatus(ctx)` to fetch detailed validation failure causes:

| Error Message            | Cause                               | Solution                                |
| ------------------------ | ----------------------------------- | --------------------------------------- |
| `"Invalid key"`          | The license key does not exist      | Verify key spelling and format          |
| `"License expired"`      | Subscription time has ended         | Renew the key on the dashboard          |
| `"HWID mismatch"`        | Key is bound to a different machine | Reset the HWID via the dashboard portal |
| `"License suspended"`    | Key was disabled by an admin        | Contact support/administration          |
| `"Max devices exceeded"` | Active device count limit reached   | Upgrade the license plan or reset HWID  |