Question 1

What is oakallow and who is it for?

Accepted Answer

oakallow is a hosted API that provides security infrastructure for AI agent tool execution.

What it does:

- Checks permissions before your AI agent executes any tool
- Routes high-risk actions through human approval workflows
- Mints cryptographic execution tokens for auditable proof
- Logs every permission check, approval, and execution

oakallow is not a monitoring platform or an AI agent framework. It is the security layer that sits between your agent and the tools it wants to run.

Who it is for:

- Developers building AI agents that execute real-world actions
- Teams that need permission governance for multi-tenant AI applications
- Anyone who wants their AI to ask before it acts

Question 2

How quickly can I get started?

Accepted Answer

Most developers are integrated within an hour.

The process:

- Create an account and get $5 in free API credits
- Generate a management API key for setup
- Register your tools, define permission rules, and create tenants
- Generate a standard API key for runtime
- Call the permission check endpoint before your agent acts

The dashboard includes a Quickstart guide and an API Builder that generates ready-to-run seed scripts.

Question 3

What are the different API key tiers?

Accepted Answer

oakallow has two API key tiers:

- Management keys are for setup and configuration. Use them to register tools, create organizations, define tenants, and set permission rules. Management operations are free. Management keys cannot access runtime endpoints.

- Standard keys are for runtime. Your AI agent uses these to check permissions, mint execution tokens, and log results. Runtime operations are billed at $0.005 per call.

Each key is scoped to a single organization. API keys are SHA-256 hashed at creation. The raw key is shown once and cannot be retrieved.

Question 4

What is an Organization in oakallow?

Accepted Answer

An Organization represents your application or project. Everything in oakallow is scoped to an organization: tools, tenants, resources, permission rules, and API keys.

If you are building a single AI agent, you will have one organization. If you are building a multi-tenant platform where each of your customers has their own AI agent, each customer can be a Tenant within your organization, with separate permission rules.

Question 5

What is a Tenant?

Accepted Answer

A Tenant represents one of your customers or end-users within your organization.

Tenants enable multi-tenant permission management. You can define permission rules that are scoped to a specific tenant, so Customer A might have different tool permissions than Customer B, all within the same organization.

Tenants are optional. If your AI agent serves a single team, you can skip tenants entirely and define permissions at the organization level.

Question 6

How does permission resolution work?

Accepted Answer

oakallow uses a 12-level resolution chain to determine the permission for any tool execution. The chain evaluates from most specific to least specific:

Tenant-scoped rules (if a tenant is specified):

- Tenant + resource + tool + method
- Tenant + resource + tool
- Tenant + tool + method
- Tenant + tool
- Tenant + resource + method
- Tenant + resource
- Tenant + method
- Tenant wildcard

Org-scoped rules (same 8 levels without tenant):

- Org + resource + tool + method through org wildcard

Fallbacks:

- Tool default permission
- Category default permission
- Tool approved status (if approved and no rules match, defaults to allowed)
- Fail-safe: requires_approval

The first match wins. If nothing matches and the tool is not pre-approved, the fail-safe is always "requires approval." Permission resolution happens at the edge via Cloudflare Workers for sub-millisecond decisions.

Question 7

What are the three permission levels?

Accepted Answer

Every permission check returns one of three results:

- allowed means the tool can execute immediately. Your agent should proceed.

- requires_approval means a human must review and approve the action before it executes. Your system should create an approval request and wait for a decision.

- disabled means the tool must not execute under any circumstances. Your agent should not attempt the action.

Question 8

How do approval workflows work?

Accepted Answer

When a permission check returns "requires_approval," your system creates an approval request via the API.

The approval request includes the tool name, parameters, reasoning, and any context your agent wants to provide.

oakallow then sends a webhook to your configured URL with the approval details (event: approval.created). Your system routes this notification to the appropriate reviewer via Slack, Teams, PagerDuty, email, or any channel you choose.

The reviewer approves or denies via the oakallow dashboard or your system calls the decide endpoint directly. oakallow sends another webhook with the decision (event: approval.decided).

Your agent receives the decision via the webhook or by polling the approval status endpoint. Once approved, you mint an execution token and proceed.

Approvals have a configurable timeout (default: 1 hour). If no decision is made within the timeout, the approval expires and the tool does not execute.

Question 9

How do approval webhooks work?

Accepted Answer

Configure a webhook URL per organization in the Settings page. oakallow sends two types of events:

- approval.created fires when your agent creates an approval request. The payload includes the tool name, parameters, reason, approval ID, and expiration time.

- approval.decided fires when a human approves or denies the request. The payload includes the decision, who decided, and any notes.

Payloads are signed with HMAC-SHA256 using your organization's webhook secret. Verify the X-Oakallow-Signature header to confirm the request is from oakallow.

Webhooks are fire-and-forget from oakallow's side. If your endpoint is unreachable, the approval still exists and can be polled via GET /v1/approvals/:id as a fallback.

Question 10

Can I automatically approve tool executions?

Accepted Answer

Yes, by setting the permission to "allowed" for that tool. Tools with "allowed" permission do not go through the approval workflow.

However, automatically approving tools that the permission system flagged as "requires_approval" is a violation of the Acceptable Use Policy. The purpose of oakallow is to ensure human oversight where you have defined it. Building systems that circumvent approval requirements defeats the security model.

Question 11

What are execution tokens?

Accepted Answer

An execution token is a single-use, HMAC-signed proof that a tool execution was authorized.

After confirming a tool is allowed (via permission check or approval), your system calls the token minting endpoint. The token contains a nonce that can only be used once, preventing replay attacks.

Tokens provide cryptographic evidence that:

- The permission was checked before execution
- The specific tool and parameters were authorized
- The token was not reused from a previous execution

Question 12

How does audit logging work?

Accepted Answer

oakallow logs every significant action:

- Permission checks record the tool, tenant, resource, method, and the resolved permission with the level it resolved from
- Approval requests record creation, decisions (approve/deny), and expiration
- Execution logs record the tool name, parameters, result (success/failed/error), duration, and the run token used

All logs include timestamps and are queryable through the dashboard Activity page and the API. Logs are scoped to your developer account.

Question 13

What operations are billable?

Accepted Answer

Billable operations (charged at $0.005 per call with a Standard key):

- Permission checks
- Parameter validation
- Token minting
- Execution logging
- Approval workflow actions

Free operations (Management key):

- Creating and managing organizations, tenants, resources, and methods
- Registering and updating tools
- Defining permission rules
- Querying activity logs
- All dashboard operations

Question 14

How are API keys secured?

Accepted Answer

API keys go through a multi-layer security process:

- At creation, the raw key is shown once and never stored. Only a SHA-256 hash is persisted.
- The key prefix (first 8 characters) is stored for identification in logs and the dashboard.
- At the edge, the Cloudflare Worker authenticates the key via KV lookup, verifies the hash, and strips the raw key from the request before forwarding to the backend.
- The Fly.io API server never sees the raw API key. It receives HMAC-signed headers with the developer ID, key ID, tier, and org scope.

If a key is compromised, revoke it immediately from the dashboard. A new key can be created in seconds.

Question 15

Where does permission resolution happen?

Accepted Answer

Permission resolution happens at the edge in a Cloudflare Worker.

Permission rules are stored in Cloudflare D1 (a serverless SQL database at the edge). When a permission check request arrives, the Worker resolves the permission locally without making a round-trip to the backend. This delivers sub-millisecond decisions.

The same permission rules are also stored in Supabase for the dashboard and API Builder. Changes made through the API are dual-written to both D1 and Supabase to keep them in sync.

Question 16

What is the infrastructure architecture?

Accepted Answer

oakallow runs on four layers:

- Cloudflare Worker handles authentication, API key verification, and permission resolution at the edge. Uses D1 for permission data and KV for key lookups.

- Fly.io hosts the API server (Node.js/Express) for tool management, token minting, approvals, execution logging, and billing.

- Supabase provides the PostgreSQL database (with Row Level Security), authentication, and file storage.

- Vercel hosts the developer dashboard and documentation.

All communication between layers uses HMAC-signed headers with a 30-second drift window for timing-safe validation.

Question 17

How does billing work?

Accepted Answer

oakallow uses a prepaid credit model.

You purchase credits via Stripe, and those credits are consumed by billable API calls at $0.005 per call. New accounts receive $5.00 in free credits (expires after 30 days).

Credit packages:

- Starter: $10 for 2,000 calls
- Builder: $25 for 5,000 calls
- Growth: $50 for 10,250 calls (includes bonus)
- Scale: $100 for 21,000 calls (includes bonus)

When your balance reaches zero, billable API calls are rejected until you add more credits. Management operations are always free regardless of balance.

Question 18

What is the refund policy?

Accepted Answer

Purchased credits that have not been consumed may be refunded within 30 days of purchase. Credits that have been partially consumed are not eligible for refund.

Free credits included with new accounts are not refundable and expire after 30 days.

To request a refund, contact support@oakallow.io.

Question 19

Can I delete my account?

Accepted Answer

Yes. Contact support@oakallow.io to request account deletion.

Upon deletion, your API keys are immediately revoked, and your personal data is removed within 30 days. Billing records may be retained as required by law.

Frequently Asked Questions

Still have questions?