agentkey-ai 1.2.1 → 1.3.0

package/README.md

@@ -35,39 +35,74 @@ The CLI never prints your key. `agentkey init` saves a pasted key to a local con
 2. Open the Connect wizard (or Agents, then create an agent).
 3. Generate an API key. It is shown once. Run `agentkey init` to save it to the local config file, or export it as `AGENTKEY_API_KEY`. Never hard-code it.
 
-## First authorization (Python)
+## First authorization (guided)
+
+Run this right after `agentkey init` (or with `AGENTKEY_API_KEY` exported). It performs ONE real, least-privilege authorization: `sandbox.send_test`, an isolated test capability every new agent ships with. It can only ever return allow or deny; it never performs a real external side effect, never touches a real tool, and grants nothing beyond that single permission. The decision is made by the real policy engine and recorded as hash-chained evidence.
+
+Python:
 
 ```python
 from agentkey import AgentKeyClient
 
-ak = AgentKeyClient(api_key="agent_live_xxxxx")  # production API by default
+ak = AgentKeyClient()  # reads AGENTKEY_API_KEY, or the config file from `agentkey init`
+
+result = ak.check_permission(action="send_test", resource="sandbox")
 
-result = ak.check_permission(action="send_email", resource="gmail", arguments={"to": "x@company.com"})
-if result["allowed"]:
-    send_email(...)  # your code
+print("session_id:       ", result.get("session_id"))
+decision = "ALLOW" if result.get("allowed") else ("APPROVAL REQUIRED" if result.get("approval_required") else "DENY")
+print("decision:         ", decision, "-", result.get("reason"))
+if result.get("event_id"):
+    print("evidence_event_id:", result["event_id"])
+    print()
+    print("YOU'RE DONE - your first real authorization was decided by the policy")
+    print("engine and recorded as verifiable evidence. See it in the dashboard:")
+    print("https://agentkey.us/sessions/" + str(result.get("session_id")))
 else:
-    print("Blocked:", result["reason"], "approval_required:", result.get("approval_required", False))
+    reason = str(result.get("reason") or "")
+    if "Invalid API key" in reason:
+        print("Your key is invalid - create one at https://agentkey.us/connect")
+    elif "No permission configured" in reason:
+        print("This agent has no sandbox.send_test permission yet. Add one in the")
+        print("dashboard (Agents -> Permissions): resource 'sandbox', action")
+        print("'send_test', decision allow - then run this again.")
+    else:
+        print("Denied by policy:", reason)
 ```
 
-## First authorization (JavaScript / TypeScript)
+JavaScript / TypeScript (save as `first-authorization.mjs`, run with `node first-authorization.mjs`):
 
 ```js
 import { AgentKeyClient } from "agentkey-ai";
 
-const ak = new AgentKeyClient({ apiKey: "agent_live_xxxxx" }); // production API by default
+const ak = new AgentKeyClient(); // reads AGENTKEY_API_KEY, or the config file from `npx agentkey init`
 
-const result = await ak.checkPermission({
-  action: "send_email",
-  resource: "gmail",
-  arguments: { to: "x@company.com" },
-});
-if (result.allowed) {
-  await sendEmail(); // your code
+const result = await ak.checkPermission({ action: "send_test", resource: "sandbox" });
+
+console.log("session_id:       ", result.session_id);
+const decision = result.allowed ? "ALLOW" : (result.approval_required ? "APPROVAL REQUIRED" : "DENY");
+console.log("decision:         ", decision, "-", result.reason);
+if (result.event_id) {
+  console.log("evidence_event_id:", result.event_id);
+  console.log();
+  console.log("YOU'RE DONE - your first real authorization was decided by the policy");
+  console.log("engine and recorded as verifiable evidence. See it in the dashboard:");
+  console.log("https://agentkey.us/sessions/" + result.session_id);
 } else {
-  console.log("Blocked:", result.reason, "approval_required:", result.approval_required ?? false);
+  const reason = String(result.reason || "");
+  if (reason.includes("Invalid API key")) {
+    console.log("Your key is invalid - create one at https://agentkey.us/connect");
+  } else if (reason.includes("No permission configured")) {
+    console.log("This agent has no sandbox.send_test permission yet. Add one in the");
+    console.log("dashboard (Agents -> Permissions): resource 'sandbox', action");
+    console.log("'send_test', decision allow - then run this again.");
+  } else {
+    console.log("Denied by policy:", reason);
+  }
 }
 ```
 
+A wrong, expired, or revoked key fails closed exactly like any other call (`allowed: false`); the scripts above tell you which case you are in.
+
 ## Decisions: allow, deny, ask
 
 `check_permission` / `checkPermission` evaluates the permissions you configured for the agent:

package/agentkey.js

@@ -19,8 +19,8 @@ const FAIL_CLOSED = { allowed: false, reason: "agentkey_unreachable", fail_close
 const TIMEOUT_MS = 5000;
 
 // Production API. Override with baseUrl only if you self-host.
-export const DEFAULT_BASE_URL = "https://agentkey.base44.app";
-export const VERSION = "1.2.1";
+export const DEFAULT_BASE_URL = "https://agentkey.us";
+export const VERSION = "1.3.0";
 const USER_AGENT = `agentkey-sdk-js/${VERSION}`;
 
 // Process-wide flag so the first-run info block prints once per process.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentkey-ai",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Authorization and evidence SDK for AI agents: check permissions before every action, record what agents actually did.",
   "type": "module",
   "bin": {
@@ -36,5 +36,5 @@
     "llm"
   ],
   "license": "MIT",
-  "homepage": "https://agentkey.base44.app"
-}
+  "homepage": "https://agentkey.us"
+}