API docs for pre-action drift checks and controlled state-package alignment.

DriftShield Align API self-service lifecycle

DriftShield Align API v0.1 uses a verified self-service access flow: register or sign in, verify email, bind a DriftShield identity receipt, start the $350/month subscription checkout, return to billing success, open Console, create an API key manually, then call check.php from your backend. Payment or subscription success does not create, display, or email an API key.

1. Create an access request

POST /api/driftshield/v1/request-key.php

{
  "account_email": "developer@example.com",
  "company_name": "Example AI Product",
  "use_case": "AI refund approval workflow",
  "api_only_boundary_confirmed": true
}

{
  "ok": true,
  "request_status": "pending_subscription",
  "subscription_status": "pending",
  "api_key_create_eligible": false,
  "identity_required": true,
  "identity_requirement": "email_verified_identity_receipt",
  "key_creation_mode": "user_console_after_active_subscription",
  "secret_display_policy": "shown_once_only_after_user_created_key",
  "secret_delivery_policy": "no_email_no_payment_success_page_no_auto_issue",
  "console_route": "?p=driftshield_console",
  "billing_success_route": "?p=driftshield_billing_success"
}

2. Verify email and bind identity receipt

GET /?p=verify_email&token=...

Email verification proves ownership of the CLARIXO account email. On successful verification, DriftShield binds a native identity receipt. Checkout, Console, API key creation, revoke, and Billing Portal actions require that receipt before inheriting account authority.

3. Start subscription checkout

POST /app/actions/originos_driftshield_checkout_create.php

{
  "access_request_id": "dsreq_...",
  "account_email": "developer@example.com",
  "product_code": "driftshield_api_monthly"
}

Checkout creates a billing handoff only after the signed-in account passes the identity gate. It does not create a key, does not reveal a secret, and does not activate access from URL parameters.

4. Return to billing success, then open Console

GET /?p=driftshield_billing_success GET /?p=driftshield_console

The billing success page is guidance only. Console eligibility must be confirmed server-side before key creation is enabled. The Console keeps subscription, API key creation, existing key prefixes, revoke, and billing controls hidden until verified identity continuity passes.

5. Create an API key in Console

POST /app/actions/originos_driftshield_api_key_create.php

API key creation requires the signed-in account, verified identity receipt, active subscription, and server-side owner checks. The plaintext secret is shown once only in the create response. DriftShield stores only hash, prefix, key id, and metadata. Lost secrets cannot be recovered; revoke and create a new key.

6. Run DriftShield check from your backend

POST /api/driftshield/v1/check.php

7. Build a Source Layer package from candidate action-state

POST /api/driftshield/v1/source.php

Use the Source Layer endpoint when your backend needs deterministic source data before a downstream governance or execution decision. The endpoint returns source_package_hash, field_provenance, canonical_packet_hash, source_receipt_id, replay_supported=true, and fixed no-execution flags.

{
  "candidate_action_state": {
    "proposed_action": {
      "value": {"action_type": "send_email"},
      "source_type": "AI_candidate",
      "generated_by_ai": true
    },
    "target_object": {
      "value": {"object_type": "email", "object_id": "email-demo-001"},
      "source_type": "object_lock"
    },
    "authority_context": {
      "value": {"authority_scope": "demo_send_request"},
      "source_type": "user_confirmation"
    },
    "inherited_state": {
      "value": {"previous_state_hash": "sha256:..."},
      "source_type": "receipt_chain"
    },
    "execution_boundary": {
      "value": {"boundary_type": "message_send"},
      "source_type": "system_declared"
    },
    "continuation_boundary": {
      "value": {"continuation_status": "fresh"},
      "source_type": "system_declared"
    }
  }
}

{
  "ok": true,
  "api_version": "driftshield-source-v0.1",
  "source_package_valid": true,
  "source_package_hash": "sha256:...",
  "field_provenance": {
    "proposed_action": "AI_candidate",
    "target_object": "object_lock",
    "authority_context": "user_confirmation"
  },
  "missing_fields": [],
  "invalid_fields": [],
  "source_receipt_id": "src_rcpt_...",
  "replay_supported": true,
  "execution_permission_granted": false,
  "workflow_modified": false,
  "external_action_executed": false,
  "hardware_attestation_claimed": false
}

Source Layer is not a final decision endpoint. It packages inspectable source data only; the customer backend or downstream DriftShield Core policy decides how that data is used.

Authentication

Authorization: Bearer YOUR_SERVER_SIDE_DRIFTSHIELD_API_KEY
Content-Type: application/json

Request schema

{
  "project_id": "billing-ai",
  "agent_id": "refund-agent",
  "session_id": "sess_123",
  "object_id": "invoice_456",
  "previous_valid_ai_state": null,
  "previous_valid_ai_state_hash": null,
  "action_boundary": "refund_approval",
  "current_ai_state": {
    "task": "review refund request",
    "target_object": "invoice_456",
    "decision": "pending"
  }
}

Response schema

{
  "ok": true,
  "api_version": "driftshield-align-v0.1",
  "mode": "controlled_alignment",
  "alignment_decision": "aligned",
  "alignment_type": "state_inheritance_rebind",
  "alignment_supported": true,
  "alignment_executed": true,
  "state_package_alignment_supported": true,
  "repair_supported": false,
  "repair_executed": false,
  "workflow_modified": false,
  "external_object_modified": false,
  "external_send_performed": false,
  "draft_created": false,
  "external_fetch_performed": false,
  "original_state_hash": "sha256:inherited_state_hash",
  "aligned_state_hash": "sha256:aligned_state_hash",
  "changed_fields": [
    "target_object",
    "target_display_name"
  ],
  "alignment_diff": {
    "target_object": {
      "from": "max",
      "to": "carl"
    }
  },
  "aligned_state": {
    "target_object": "carl",
    "decision": "pending"
  },
  "aligned_context": {
    "target_id": "carl",
    "target_display_name": "Carl"
  },
  "reason": "The inherited state targeted Max, while the valid-state source confirms Carl.",
  "developer_hint": "Continue only with aligned_context.",
  "receipt_id": "dsalign_..."
}

{
  "ok": true,
  "decision": "drift_detected",
  "drift_type": "state_inheritance_drift",
  "report_level": "blocked",
  "reason": "The current AI state does not inherit from the previous valid state.",
  "developer_hint": "Pause the sensitive action inside your own product boundary.",
  "receipt_id": "dsr_..."
}

Error codes

curl example

curl -X POST "https://clarixo.fun/api/driftshield/v1/check.php" \
  -H "Authorization: Bearer YOUR_SERVER_SIDE_DRIFTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "billing-ai",
    "agent_id": "refund-agent",
    "session_id": "sess_123",
    "object_id": "invoice_456",
    "previous_valid_ai_state": null,
    "previous_valid_ai_state_hash": null,
    "action_boundary": "refund_approval",
    "current_ai_state": {
      "task": "review refund request",
      "target_object": "invoice_456",
      "decision": "pending"
    }
  }'

Server-side JavaScript / Node.js example

Run this only from your backend. Store the API key in a private server-side environment variable. Never expose the DriftShield API key in browser JavaScript, mobile client code, public HTML, or frontend bundles.

const response = await fetch("https://clarixo.fun/api/driftshield/v1/check.php", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DRIFTSHIELD_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    project_id: "billing-ai",
    agent_id: "refund-agent",
    session_id: "sess_123",
    object_id: "invoice_456",
    previous_valid_ai_state: null,
    previous_valid_ai_state_hash: null,
    action_boundary: "refund_approval",
    current_ai_state: {
      task: "review refund request",
      target_object: "invoice_456",
      decision: "pending"
    }
  })
});

const driftshield = await response.json();

if (driftshield.decision === "drift_detected") {
  // Pause inside your own product boundary.
}

PHP example

$payload = [
    "project_id" => "billing-ai",
    "agent_id" => "refund-agent",
    "session_id" => "sess_123",
    "object_id" => "invoice_456",
    "previous_valid_ai_state" => null,
    "previous_valid_ai_state_hash" => null,
    "action_boundary" => "refund_approval",
    "current_ai_state" => [
        "task" => "review refund request",
        "target_object" => "invoice_456",
        "decision" => "pending",
    ],
];

$apiKey = getenv("DRIFTSHIELD_API_KEY");

$ch = curl_init("https://clarixo.fun/api/driftshield/v1/check.php");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . $apiKey,
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$result = curl_exec($ch);
curl_close($ch);

$driftshield = json_decode((string) $result, true);

Developer backend integration guide

This guide applies to DriftShield Align API v0.1, the $350/month self-service developer API. Your backend calls the API before AI output, stores only the safe response fields you need, and decides how your own product should handle session_init, no_drift, drift_detected, quota_exceeded, or rate_limited. CLARIXO Governance / Continuity API is a separate broader governance entry that starts from $2,500/month and requires integration review.

// Example safe monitor event written by your backend
const safeEvent = {
  timestamp: new Date().toISOString(),
  source: "your_ai_backend",
  session_id_hash: sha256(session_id),
  object_id: object_id,
  action_boundary: action_boundary,
  status: "connected",
  api_call: "called",
  decision: driftshield.decision,
  drift_type: driftshield.drift_type,
  report_level: driftshield.report_level,
  receipt_id: driftshield.receipt_id,
  report_id: driftshield.report_id,
  possible_drift_nodes_count: Array.isArray(driftshield.possible_drift_nodes)
    ? driftshield.possible_drift_nodes.length
    : 0,
  alignment_supported: driftshield.alignment_supported === true,
  alignment_executed: driftshield.alignment_executed === true,
  state_package_alignment_supported: driftshield.state_package_alignment_supported === true,
  repair_supported: false,
  repair_executed: false,
  workflow_modified: false,
  correction_executed: false,
  user_ui_prompt: false,
  raw_message_logged: false,
  raw_attachment_logged: false,
  api_key_logged: false
};

await privateEventLog.append(safeEvent);

// Example backend handling shape
const driftshield = await response.json();

await db.driftshield_checks.insert({
  receipt_id: driftshield.receipt_id,
  report_id: driftshield.report_id || null,
  mode: driftshield.mode || driftshield.alignment_mode || "observe_only",
  decision: driftshield.decision || driftshield.alignment_decision,
  drift_type: driftshield.drift_type || driftshield.risk_type || null,
  report_level: driftshield.report_level || null,
  alignment_supported: driftshield.alignment_supported === true,
  alignment_executed: driftshield.alignment_executed === true,
  repair_supported: false,
  repair_executed: false,
  reason: driftshield.reason,
  developer_hint: driftshield.developer_hint
});

if (driftshield.alignment_executed === true && driftshield.aligned_context) {
  // Continue only with the returned aligned_context inside your own backend.
  // DriftShield does not modify the customer workflow.
} else if (
  driftshield.decision === "drift_detected"
  || driftshield.alignment_decision === "needs_confirmation"
  || driftshield.alignment_decision === "blocked"
  || driftshield.report_level === "blocked"
) {
  // Pause or route the action inside your own product boundary.
  // DriftShield does not modify the customer workflow.
}