Backend & API Reference

📚 Backend & API Reference

Reference for the XE backend call, the gkas_config you send to the page, and the collector's init function.

🔒 The gkas_solution is an opaque token. Its contents and format are intentionally not documented. Your backend forwards it unchanged to checkaccessxe; you never read, build or parse it.

Frontend: `gkas_init(...)`

Provided by the hosted GuardianKey script (gkas-setup-latest.js). Hooks the login form and builds the gkas_solution on submit.

gkas_init(gkas_config, formElement, usernameFieldName, debug = false)

Parameter	Type	Description
`gkas_config`	object	The `{ url, salt, once, time }` your backend generated for this page load.
`formElement`	HTMLFormElement	The login form to hook.
`usernameFieldName`	string	Name of the username input — bound into the attempt.
`debug`	boolean	Optional. Shows a diagnostic panel. Default `false`.

On submit, the collector injects a hidden gkas_solution field into the form, so the POST your backend receives includes it automatically.

`gkas_config` (page → collector)

Built per page load by your backend and embedded in the page. Same fields the backend later passes to checkaccessxe.

Field	Type	Description
`url`	string	The page/endpoint origin + path. Part of the bound challenge.
`salt`	string	A per‑deployment salt.
`once`	string	One‑time nonce — generate per load, store in session, validate on POST.
`time`	string	Unix timestamp (as string) of generation.

{
  "url":  "https://app.example.com/login.php",
  "salt": "demo_salt",
  "once": "9f1c…",
  "time": "1754428303"
}

Backend: `checkaccessxe(...)`

From the reference guardiankey.class.php. Sends the backend event and the frontend gkas_solution to GuardianKey, returning a JSON decision.

function checkaccessxe(
    $username,
    $useremail = "",
    $url, $salt, $once, $time,
    $gk_solution,        // the opaque gkas_solution from the POST, unchanged
    $attempt = "0"       // "0" = correct password, "1" = failed
)

Parameter	Description
`$username`	The user identifier from the login form.
`$useremail`	Optional email; `""` if unused.
`$url`, `$salt`, `$once`, `$time`	The same values from the `gkas_config` of this attempt.
`$gk_solution`	The `gkas_solution` received in the POST — forward unchanged.
`$attempt`	`"0"` if the password was correct, `"1"` otherwise.

Internally it POSTs to …/v3/gkas/{authgroupid}/checkaccessxe with the X-Api-Key header, wrapping a backend_data event and a frontend_data ( gkas_solution, url, salt, once, time ). No change to the reference class is required — it forwards the token as‑is.

`GKconfig` (credentials)

Construct the client with your GuardianKey credentials. These live only on the backend — never in the page.

$GKconfig = [
    'agentid'     => 'sdk',
    'key'         => 'BASE64_KEY',
    'iv'          => 'BASE64_IV',
    'service'     => 'YourServiceName',
    'orgid'       => 'YOUR_ORG_ID',
    'authgroupid' => 'YOUR_AUTHGROUP_ID',
    'api_key'     => '',                  // derived below
    'reverse'     => 'True',
];
// api_key = sha256(key + iv)
$GKconfig['api_key'] = hash('sha256', $GKconfig['key'] . $GKconfig['iv']);

Response

checkaccessxe returns a JSON string with the same model as classic Auth Security. The decisive field is response:

{
  "response": "ACCEPT",
  "risk": 5.047,
  "risk_context": 5.0,
  "risk_intel": 0.05,
  "country": "Brazil",
  "client_os": "Linux",
  "client_ua": "Chrome",
  "eventId": "3e1c389c1ae49efc…",
  "message": "Origin not found in the threat DB."
}

`response`	Action
`ACCEPT`	Allow access.
`NOTIFY`	Allow, optionally with extra verification / user notification.
`BLOCK`	Deny access, even if the password was correct.

⚠️ Always validate the response before granting access. On BLOCK, return a generic message ("invalid username or password") to avoid information leakage.