C++ SDK: Auth Flow & Error Surfaces

C++ SDK: Auth Flow & Error Surfaces

The C++ SDK and the Luau library both authenticate against the same Aureva backend, but they do different amounts of work and they surface different error codes. This page makes both distinctions explicit so you don’t conflate the two.

---

Heavy flow vs. lightweight flow

The C++ SDK uses the full protocol session (heavy)

When you call license() and check(), the C++ SDK runs the full Aureva protocol-v4 session:

1. init — assemble and POST the encoded init request (carrying your client version), then verify-then-decrypt the response and establish a session.
2. verify-alive — confirm the session proof with the backend before the session is trusted.
3. heartbeat / key rotation — keep the session alive with periodic, authenticated heartbeats (WebSocket-first, HTTP fallback) and rotate the per-session keys on a fixed cadence.

This is the same heavy flow the embedded Lua whitelist runs internally. It maintains a live, server-tracked session with ongoing integrity checks — appropriate for a native application that stays running and must react to a mid-session kick or revocation.

The Luau loader uses a lightweight check (light)

The documented Luau library flow is a lightweight loader check: you set a key (or pass it on the loader URL) and call Aureva.check_key, and Aureva validates the key server-side before delivering the script. See Key Validation for that flow.

That is a one-shot validation gate in front of script delivery — it is not the long-lived init → verify-alive → heartbeat / rotation session the C++ SDK maintains.

Caution

Do not assume the C++ SDK behaves like Aureva.check_key. The C++ license() / check() calls are a full session lifecycle, not a single key-validation request. Plan for the heavier flow: run activation off your hot path and call check() on a fixed interval.

Aspect	Luau loader	C++ SDK
Shape	One-shot Aureva.check_key before script delivery	Full session: init → verify-alive → heartbeat / rotation
Lifetime	Validate once, then load	Long-lived session, kept alive and re-validated
Entry point	Aureva.check_key("USER_KEY")	app.license(key) then periodic app.check()
Distribution	Embedded into your script, co-obfuscated	Downloaded static library + header

---

Two distinct error surfaces

The Luau client and the C++ SDK report errors through different code surfaces. They are not the same set of codes, and one does not replace the other — they describe failures at different layers.

Luau KEY_* key-validation codes

The Luau library returns key-validation codes such as KEY_INVALID, KEY_EXPIRED, KEY_HWID_LOCKED, and KEY_BANNED. These describe the outcome of a key check.

These codes, their meanings, the recommended handling, the HWID-reset guidance, and the ban / blacklist guidance are documented in:

• Key Validation — the KEY_* codes and how to handle each
• Error Codes — the full reference, including HWID-reset and ban / blacklist handling

This C++ page does not redefine those codes. Use the existing references above for the Luau key-validation surface.

Protocol-v4 A-0x.. / E-0x.. denial codes (C++ SDK)

When the C++ SDK denies authorization, it records and logs a denial reason code from the protocol-v4 denial scheme. These codes identify the failing step in the session flow, which is a different layer from a key-validation result:

• A-0x.. codes mark auth-flow steps — for example a blacklisted result, an invalid or absent HWID, a missing or placeholder embedded config, an init transport failure, a verify-alive proof mismatch, a verified kick, or a reported client version below the application’s minimum.
• E-0x.. codes mark integrity / tamper self-test failures — for example a time-desync beyond the allowed threshold, a CSPRNG statistical self-test failure, or a crypto self-test mismatch.

The denial code is surfaced through the SDK’s diagnostic log sink alongside a short, non-secret message; app.response.message gives you a non-secret human-readable reason. The codes never carry key or secret material.

Note

The A-0x.. / E-0x.. codes are a separate surface from the Luau KEY_* codes. A KEY_EXPIRED result from the Luau loader and an A-0x.. auth-flow denial from the C++ SDK live at different layers: the first is a key-validation verdict returned to a Luau caller; the second identifies which step of the native session flow denied. Don’t map one onto the other one-for-one.

How the two surfaces relate

	Luau KEY_* codes	C++ A-0x.. / E-0x.. codes
Layer	Key-validation result	Session-flow denial step / integrity self-test
Reported by	Luau library (Aureva.check_key)	C++ SDK denial path
Surfaced via	result.code / result.message	Diagnostic log sink + response.message
Reference	Key Validation, Error Codes	This page (categories), plus the SDK’s logged code
HWID reset / ban guidance	Error Codes	Reuse the same HWID-reset and ban guidance — not redefined here

For HWID-reset steps and ban / blacklist handling, follow the existing guidance in Error Codes and Key Validation. The C++ SDK does not re-invent that guidance; the same dashboard, Discord, and support flows apply.

---

Next steps

• Getting Started — download, build, and call the SDK
• Thread-Safety Contract — concurrency rules
• Error Codes — the existing KEY_* reference and HWID-reset / ban guidance