oakallow API Reference

Introduction

oakallow provides a hosted API for governing AI agent tool execution. Instead of building your own permission system, token minting, approval workflows, and audit trails, integrate with oakallow's API and get production-grade security infrastructure in minutes.

The API is organized around REST. All requests and responses use JSON. All endpoints (except health check) require authentication via API key.

Authentication

Authenticate by including your API key in the X-API-Key header on every request. API keys are scoped to a single organization. There are three key types:

Management keys are for setup and configuration — seeding tools, creating tenants, managing permission rules. They cannot access runtime endpoints (permission checks, approvals). Use these in CI/CD pipelines and configuration scripts.

Standard keys are for runtime — your agent uses these to check permissions, mint tokens, drive approval workflows, and log executions. They can read (GET) management resources but cannot create or modify them. Every runtime call is $0.005.

Route only the actions you want governed. oakallow is for the moments that matter: gated, approved, audited. If a tool fires thousands of times an hour and never needs a human in the loop, register it with default_permission: allowed and skip the permission check entirely. Per-call pricing is charged for governed-action volume, not application telemetry — keep general logging in your own observability stack.

curl https://api.oakallow.io/v1/tools \
  -H "X-API-Key: oak_live_your_key_here"

Keys are created in the oakallow dashboard. Each key is bound to one organization — you cannot access another organization's data with a different key. The organization scope is enforced at the edge and cannot be overridden.

Key format: oak_live_ followed by 32 hex characters. The first 17 characters are used as a lookup prefix (collision-safe at 32 bits of entropy). Never share your full API key.

Base URL

https://api.oakallow.io

All API endpoints are prefixed with /v1. Requests are authenticated and rate-limited at the Cloudflare edge before reaching the origin server.

Errors

oakallow uses standard HTTP status codes.

Error responses include a JSON body:

{
  "error": "tool_name is required"
}

Data Model

oakallow's data model is a hierarchy. Every entity is scoped to a developer (you).

Developer (you — authenticated via API key)
  └── Organization (your app — API key is scoped to one org)
       ├── Tenants (your customers)
       ├── Resources (servers, databases, endpoints — targets)
       ├── Methods (ssh, api, cli — how tools execute)
       ├── Tool Categories (health, security — with default permissions)
       ├── Tools (check_memory, restart_service, etc.)
       └── Permission Rules
            └── tenant + resource + tool + method → permission

Organizations represent your application. Each API key is bound to one org.

Tenants represent your customers. They are optional — if your app is single-tenant, you can skip tenants entirely and define permissions at the org level.

Resources are the targets that tools operate on: servers, databases, API endpoints, Kubernetes namespaces, etc. You define the external_id (your own identifier).

Tools are the actions your AI agent can perform. Tools are org-scoped — each organization has its own tool catalog. The same tool name in different orgs are separate tools. Each tool has a name, category, risk level, and optional parameters schema.

Permission Rules map combinations of tenant + resource + tool + method to a permission level: allowed, requires_approval, or disabled.

Permission Resolution

When you check a permission, oakallow walks a 12-level resolution chain from most specific to least specific. The first match wins.

If tenant_id is provided, tenant-scoped rules are checked first:
  Level 1:  tenant + resource + tool + method
  Level 2:  tenant + resource + tool
  Level 3:  tenant + resource + method
  Level 4:  tenant + resource
  Level 5:  tenant + tool + method
  Level 6:  tenant + tool              ← most common tenant rule
  Level 7:  tenant + method
  Level 8:  tenant + tag match

Then org-wide rules (tenant_id = NULL):
  Same 8 levels as above

Defaults:
  Level 9:  tool.default_permission
  Level 10: tool_category.default_permission
  Level 11: tool_approved → allowed (if tool status is approved)
  Level 12: fail_safe → requires_approval

If a tool has status: approved and no rules or defaults match, it resolves as allowed (Level 11). Only unapproved tools fall through to the fail-saferequires_approval at Level 12.

Tier gating:Tools can require a minimum tier. If your API key's tier is lower than the tool's required_tier, the permission check returns disabled with resolved_from: "insufficient_tier".

Onboarding Flow

To fully integrate with oakallow, make API calls in this order. Steps 1-7 use a management key (free). Steps 8-10 use a standard key (billed).

Organizations

Organizations represent your application. Your API key is already scoped to one org. Use this endpoint to verify your org exists and retrieve its external_id.

{
  "orgs": [
    {
      "id": "uuid",
      "external_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
      "name": "My App",
      "created_at": "2026-03-21T03:49:07Z"
    }
  ],
  "count": 1
}

{
  "name": "My Production App"
}

{
  "id": "uuid",
  "external_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "name": "My Production App",
  "created_at": "2026-03-21T03:49:07Z"
}

Approval Webhook Configuration

Configure via the dashboard Settings page or programmatically via the API. The webhook secret is auto-generated on first setup. To regenerate, pass regenerate_secret: true.

{
  "approval_webhook_url": "https://your-app.com/webhooks/oakallow",
  "webhook_secret": "a1b2c3...hex64",
  "message": "Save this secret. It will not be returned again."
}

Tenants

Tenants represent your customers within an organization. They are optional — if your app is single-tenant, skip this step and define permissions at the org level. Tenant external IDs are auto-generated with a ten_ prefix.

POST /v1/orgs/org_ftcECvT5dtdjIEgFCe6hGniT/tenants

{
  "name": "Acme Corp",
  "metadata": { "plan": "enterprise", "region": "us-east" }
}

{
  "id": "uuid",
  "external_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "name": "Acme Corp",
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "created_at": "2026-03-21T03:50:06Z"
}

{
  "tenants": [
    {
      "id": "uuid",
      "external_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
      "name": "Acme Corp",
      "metadata": "{}",
      "created_at": "2026-03-21T03:50:06Z"
    }
  ],
  "count": 1
}

Deleting a tenant cascades to all its permission rules and resources.

Resources

Resources are targets that tools operate on — servers, databases, API endpoints, Kubernetes namespaces, S3 buckets, etc. You provide the external_id (your own identifier).

POST /v1/orgs/org_ftcECvT5dtdjIEgFCe6hGniT/resources

{
  "external_id": "server-prod-01",
  "name": "Production Server",
  "metadata": {
    "ip": "64.225.125.239",
    "provider": "digitalocean",
    "os": "linux"
  }
}

{
  "id": "uuid",
  "external_id": "server-prod-01",
  "name": "Production Server",
  "metadata": { "ip": "64.225.125.239", "provider": "digitalocean", "os": "linux" },
  "created_at": "2026-03-23T..."
}

Deleting a resource cascades to all permission rules scoped to it.

{
  "resources": [
    { "external_id": "server-prod-01", "name": "Prod Server", "metadata": {} },
    { "external_id": "server-staging-01", "name": "Staging Server", "metadata": {} },
    { "external_id": "db-prod", "name": "Production Database", "metadata": {} }
  ]
}

Methods

Methods define how tools are executed — your vocabulary for execution patterns. Common methods: ssh, go_agent, api, cli,manual, scheduled.

{
  "name": "ssh",
  "description": "Execute via SSH connection to the target server"
}

Tool Categories

Categories group tools and provide a default permission for the group. If a tool has no specific permission rule and no tool-level default, the category default is used.

Note: Category management endpoint is coming soon. Categories are currently created via the dashboard or when tools reference them during seeding.

Tools

Tools are the actions your AI agent can perform. Each tool has a name, description, category, risk level, parameter schema, and tier requirement.

{
  "tools": [
    {
      "id": "uuid",
      "name": "check_memory",
      "description": "Check system memory usage and availability",
      "category": "health",
      "risk_level": "read_only",
      "required_tier": "standard",
      "status": "approved",
      "default_permission": null,
      "requires_second_approval": false,
      "approval_timeout_seconds": null,
      "parameters": {
        "threshold_percent": {
          "type": "integer",
          "description": "Alert threshold percentage",
          "default": 90
        }
      }
    }
  ],
  "count": 1
}

Tool Seeding

The seed endpoint is designed for bulk tool registration. It performs an idempotent upsert — creates tools that don't exist and updates those that do. You can optionally include permission rules inline with each tool.

{
  "tools": [
    {
      "name": "check_memory",
      "description": "Check system memory usage and availability",
      "category": "health",
      "risk_level": "read_only",
      "required_tier": "standard",
      "status": "approved",
      "requires_second_approval": false,
      "parameters": {
        "threshold_percent": {
          "type": "integer",
          "description": "Alert threshold percentage",
          "default": 90
        }
      },
      "tags": {
        "tool_types": ["ssh"],
        "os": "linux",
        "readOnly": true
      },
      "permissions": [
        {
          "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
          "permission": "allowed"
        },
        {
          "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
          "resource_id": "server-prod-01",
          "permission": "allowed"
        }
      ]
    }
  ]
}

Important: The tenant_id and resource_idreferenced in permissions must already exist. The seed endpoint looks them up by external_id — if they don't exist, the permission rule is skipped and reported in the errors array.

{
  "tools_created": 1,
  "tools_updated": 0,
  "rules_created": 2,
  "rules_updated": 0,
  "errors": []
}

Permission Check

Check whether a tool execution is allowed for a given context. This is the hot path — single-digit millisecond resolution at the Cloudflare edge.

{
  "tool_name": "check_memory",
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "resource_id": "server-prod-01",
  "method": "ssh"
}

{
  "permission": "allowed",
  "resolved_from": "tenant_resource_tool_method",
  "resolved_level": 1,
  "tool_id": "uuid",
  "tool_status": "approved",
  "category": "health",
  "resource_id": "server-prod-01",
  "method": "ssh",
  "_timing": { "resolve_ms": 4, "auth": "cache" }
}

The resolved_from field tells you which level of the permission chain matched. This is invaluable for debugging why a tool is allowed or blocked.

Note: The org_id is not in the request body — it comes from your API key. You cannot check permissions for a different organization.

Permission Rules

Permission rules define the access control for your tools. Each rule maps a combination of tenant + resource + tool + method to a permission level.

{
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "tool_name": "check_memory",
  "permission": "allowed"
}

{
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "resource_id": "server-prod-01",
  "tool_name": "restart_service",
  "method": "ssh",
  "permission": "requires_approval"
}

{
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "permission": "requires_approval"
}

{
  "id": "uuid",
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "resource_id": null,
  "tool_name": "check_memory",
  "method": null,
  "permission": "allowed",
  "created": true
}

Rules are upserted — if a rule with the same combination of fields already exists, the permission is updated instead of creating a duplicate.

Query parameters: org_id, tenant_id, tool_name, method.

Bulk Rules

{
  "rules": [
    {
      "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
      "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
      "tool_name": "check_memory",
      "permission": "allowed"
    },
    {
      "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
      "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
      "tool_name": "restart_service",
      "resource_id": "server-prod-01",
      "method": "ssh",
      "permission": "requires_approval"
    },
    {
      "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
      "tool_name": "check_memory",
      "permission": "allowed"
    }
  ]
}

{
  "created": 2,
  "updated": 1,
  "errors": []
}

Sync Rules

Full state sync — replaces all existing rules for an org/tenant scope with a new set. This is what a drag-and-drop permission UI calls on Save.

{
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "rules": [
    { "tool_name": "check_memory", "permission": "allowed" },
    { "tool_name": "check_cpu", "permission": "allowed" },
    { "tool_name": "restart_service", "permission": "requires_approval" },
    { "tool_name": "drop_caches", "permission": "disabled" }
  ]
}

Warning: This deletes all existing rules for the given org + tenant scope before inserting the new rules. Omit tenant_id to sync org-level rules.

Token Minting

Execution tokens are single-use, time-limited HMAC tokens that authorize a specific tool execution. Mint a token after the permission check passes, then include it when executing the tool.

{
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "tool_id": "uuid-from-permission-check",
  "params": { "threshold_percent": 90 },
  "ttl_seconds": 120,
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe"
}

{
  "token_id": "uuid",
  "tool_id": "uuid",
  "params_hash": "sha256-hex",
  "nonce": "unique-nonce",
  "expires_at": "2026-03-23T12:02:00Z",
  "hmac": "hex-signature"
}

Approvals

When a permission check returns requires_approval, your agent should request approval before executing the tool. Approvals have a configurable timeout (default: 1 hour).

Approval Webhooks

Configure an approval webhook URL per organization in the Settings page. When an approval request is created, oakallow sends a POST to your webhook URL with the event type approval.created and the approval details (tool name, reason, reference ID, approval ID, expiration). When a human decides, another webhook fires with approval.decidedand the decision. Webhook payloads contain only the redacted data stored by oakallow.

Payloads are signed with HMAC-SHA256 using your webhook secret. Verify the X-Oakallow-Signature header (sha256=<hex>) to confirm authenticity. You can also poll GET /v1/approvals/:id as an alternative or fallback.

{
  "event": "approval.created",
  "timestamp": "2026-03-24T12:00:00Z",
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "data": {
    "approval_id": "uuid",
    "tool_name": "restart_service",
    "reason": "Service restart requested",
    "reference_id": "incident-4821",
    "status": "pending",
    "expires_at": "2026-03-24T13:00:00Z",
    "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe"
  }
}

{
  "event": "approval.decided",
  "timestamp": "2026-03-24T12:05:00Z",
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "data": {
    "approval_id": "uuid",
    "tool_name": "restart_service",
    "reference_id": "incident-4821",
    "decision": "approved",
    "decided_by": "admin@example.com",
    "note": "Confirmed safe to restart"
  }
}

API Endpoints

{
  "approval_id": "uuid",
  "status": "pending",
  "expires_at": "2026-03-23T13:00:00Z",
  "reference_id": "incident-4821"
}

Each approval includes a display reference number in the format REF-XXXXXXXX-XXXX (derived from the approval UUID). This reference number also appears on linked execution logs in the dashboard, making it easy to trace an execution back to its approval.

Execution Logging

Log every tool execution for audit trail. This is called after the tool runs, regardless of whether it succeeded or failed.

{
  "org_id": "org_ftcECvT5dtdjIEgFCe6hGniT",
  "tool_name": "check_memory",
  "tool_id": "uuid",
  "run_token_id": "uuid",
  "execution_result": "success",
  "duration_ms": 42,
  "triggered_by": "ai_agent",
  "tenant_id": "ten_lLxSMc0CwLMbgGwCPA3Y95Xe",
  "approval_request_id": "uuid",
  "metadata": {
    "memory_used_percent": 67,
    "memory_total_gb": 8
  }
}

Query parameters: org_id, tenant_id, tool_name, execution_result, approval_request_id.

Executions that include an approval_request_id are linked to their approval record in the dashboard. The approval status, decision, and reference number are displayed alongside the execution details.