> For the complete documentation index, see [llms.txt](https://easyauth.papelship.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyauth.papelship.com/documentation/core-functions/session-authentication.md).

# Session Authentication

This page details network establishment, session negotiation, computer registration, and license key verification.

## Network Connection

### `easyauth::network_connect`

Establishes a high-speed encrypted TCP tunnel with the EasyAuth cluster.

```cpp
bool network_connect(const char* host = nullptr, uint16_t port = 0);
```

#### Parameters

* `host` *(Optional)*: Custom server IP or domain. Pass `nullptr` to use default embedded cluster endpoint.
* `port` *(Optional)*: Custom port. Pass `0` to use standard default port (`7710` / `8888`).

#### Returns

* `true` if TCP handshake and session key exchange succeeded; `false` otherwise.

#### Example

```cpp
if (!easyauth::network_connect()) {
    std::cerr << "[-] Unable to connect to auth server.\n";
    return 1;
}
```

### `easyauth::network_is_connected` & `easyauth::network_disconnect`

Inspect connection health or gracefully close the active session tunnel.

```cpp
bool network_is_connected();
void network_disconnect();
```

### `easyauth::network_ping`

Measures round-trip latency to the server cluster in milliseconds.

```cpp
bool network_ping(uint32_t& out_latency_ms);
```

## Session & Authentication

### `easyauth::init_session`

Initializes a secure, authenticated pre-session using the Product Public API Key. Performs anti-tamper CRC verification and fetches remote configuration policies.

```cpp
session_init_result init_session(const std::string& api_key = "");
```

#### Return Structure (`session_init_result`)

```cpp
struct session_init_result {
    bool success;           // true if session is valid and tamper-free
    std::string error_name; // Error identifier (e.g., "TAMPER_DETECTED")
    std::string message;    // Detailed human-readable status message
};
```

### `easyauth::authenticate`

Validates a user's license key against the server, verifies Hardware ID (HWID) lock, and binds the session to the authenticated user.

```cpp
auth_result authenticate(const std::string& key, const std::string& api_key = "");
```

#### Parameters

* `key`: User license key (e.g. `EASY-ABCD-1234-WXYZ`).
* `api_key` *(Optional)*: Product API key. If omitted, uses the key from `set_config`.

#### Return Structure (`auth_result`)

```cpp
struct auth_result {
    bool success;           // true if key is valid, active, and HWID matches
    int error_code;         // Numeric status code
    std::string error_name; // Error code string (e.g. "KEY_EXPIRED", "HWID_MISMATCH")
    std::string message;    // Server explanation message
    std::string expire_date;// Expiration timestamp (e.g. "2026-12-31 23:59:59")
};
```

#### Example

```cpp
std::string user_key = "EASY-TEST-LICENSE-KEY";
std::string api_key = _XOR_("pk_00000073_1381695181994e4ea94eabf54911520b");

auto auth_res = easyauth::authenticate(user_key, api_key);
if (auth_res.success) {
    std::cout << "[+] Welcome! Expiry Date: " << auth_res.expire_date << "\n";
} else {
    std::cerr << "[-] Auth Error: " << auth_res.message << " (" << auth_res.error_name << ")\n";
}
```

### `easyauth::register_computer`

Registers the client machine hardware profile (CPU ID, Motherboard UUID, MAC, Specs) without consuming a key.

```cpp
auth_result register_computer(const std::string& api_key = "");
```