Permissions & Approvals

oakallow resolves every tool call from most specific to least specific, and the first match wins. There are three stages.

• The tool must exist in your catalog, be enabled for the org, and meet the tool's required tier. Fail any gate and the result is disabled — the walk never starts.

• resource + tool + method, then resource + tool, resource + method, resource, tool + method, tool, method, and finally a tag match.
• If the request names a tenant and tenant-scoped rules exist, the tenant set is walked first, then the org set. If there are no tenant rules, the org set is the only set.

• The tool's default permission, then its category default, then "allowed" if the tool itself is approved, and finally the fail-safe: requires_approval.

Nothing is cached — every call is re-evaluated. If nothing matches and the tool is not pre-approved, the fail-safe is always requires_approval. Resolution runs at the edge in a Cloudflare Worker with single-digit millisecond latency.

• 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.

When a permission check returns "requires_approval," your system creates an approval request via the REST 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 mobile app, 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.

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.

Add a Slack notification channel from Settings → Notification Channels. Click "Add to Slack" to authorize the Oakallow Slack app in your workspace and pick a channel — we fill the webhook URL in for you. Manual paste is also supported if you would rather create your own incoming webhook in Slack.

• Approval requested when an agent's action needs review
• Approval granted or denied when a decision is recorded
• Approval expired when a request times out without a decision

Each card shows the tool name, a short PII-scrubbed reason, and an oakallow reference id (REF-XXXXXXXX-XXXX). We never send tool parameters, customer data, or other identifying details to Slack.

This is alerting only. Approval decisions are made exclusively in the Oakallow mobile app with enforced multi-factor authentication. Slack delivers the alert; the mobile app handles the decision. This separation keeps your audit trail intact and ensures every decision is signed by a verified, authorized approver — never by someone who happens to have access to a Slack channel.

You can scope each Slack channel to fire team-wide (every approval), only when Level 1 approvers are being asked, or only when Level 2 approvers are being asked. The Slack app requests the incoming-webhook scope only — it cannot read messages, send DMs, or access workspace data.

Add a PagerDuty notification channel from Settings → Notification Channels. You will need three things from your PagerDuty account:

• API Key: a General Access API Key (not Read-Only). Find it in PagerDuty → Integrations → API Access Keys, then copy the API Key value (not the ID column).
• PagerDuty User Email: the email of an actual user in your PagerDuty account. This is the requester recorded against incidents Oakallow creates.
• Service ID: open Services → Service Directory, click your service, and copy the ID from the URL (it appears as /service-directory/<ID>). This is NOT the integration ID and NOT the API Key ID — those look identical but are different things.

When an approval event fires, Oakallow creates an incident on your PagerDuty service. The Service's Escalation Policy decides who gets paged. Each incident shows the tool name, the oakallow reference id, and a short PII-scrubbed reason. We never send tool parameters, customer data, or end-user identities to PagerDuty.

• Approval requested creates an incident at your default urgency.
• Approval granted or denied resolves the matching incident.
• Approval expired creates an incident at high urgency regardless of the default — this is the case where someone needs to look at a request that timed out.

This is alerting only. Approvals are still decided exclusively in the Oakallow mobile app with enforced multi-factor authentication. PagerDuty pages the right human; the mobile app is where the decision is made and signed.

The API Key is stored encrypted at rest and is write-only after creation — we never display it back to you. To rotate, edit the channel in Settings, paste the new key, save, and click Test to confirm delivery.

• Event type (approval.created, approval.decided, approval.expired)
• Tool name
• A PII-scrubbed reason string (max 200 characters, automatic redaction of common PII patterns before storage)
• The oakallow reference id (REF-XXXXXXXX-XXXX) for cross-system traceability
• For decided events: the decision (approved or denied), the decider, and any note

• Tool input arguments or parameters
• End-user identities, names, or other identifying details
• Customer data of any kind beyond the tool name itself
• API keys, tokens, or any credential material

The purpose of notifications is to tell you that a decision is needed, not to relay the data the decision is about. Anything sensitive stays inside oakallow itself — open the request in the dashboard or the mobile app to see the full context.

The destinations you configure (Slack workspaces, PagerDuty services, webhook endpoints) are services you choose. Their handling of these notifications is governed by their own data policies, not oakallow's. You are responsible for what you configure.

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.

oakallow supports optional two-level approvals, where a request escalates from a first approver to a second approver before a tool runs.

• Under the Team page, admins and owners configure two groups: Approval 1 and Approval 2. Add team members to each group to control who receives approval pushes and who can act on them. If a group is empty, it falls back to every active team member.

• On the Tools page, flag the tool with "Requires second approval." When that tool triggers an approval request, the request starts at level 1 and is routed to the Approval 1 group. After the first approver approves, the request advances to level 2 and is routed to the Approval 2 group. Either level can deny, which ends the request.

• Two-level escalation only kicks in when the Approval 2 group has at least one member. If it is empty, the request stays single-level and is resolved by Approval 1 alone. Tools without the flag always stay single-level.

Every approval request has an expiration. If no decision is made before it expires, the request is auto-marked as expired and the tool does not execute. Expired requests stay visible on the dashboard's Recent Activity and Activity feeds so nothing disappears silently.

• On the Organizations page, set an Approval timeout for the org (presets: 5 minutes, 15 minutes, 1 hour, 4 hours, 24 hours, 3 days, 7 days). This applies to every tool in that org unless the tool overrides it.

• On the Tools page, each tool has a Timeout column. Leave it as "Default (org setting)" to inherit, or pick a preset to override for that tool only.

• At request time, oakallow resolves the timeout in this order: tool setting, then org setting, then a 1-hour fallback. Values are clamped between 60 seconds and 7 days.

• REST callers can also seed an override via the API. POST /v1/approvals/request accepts an optional timeout_seconds field. When provided, the value is persisted to the per-tool override (org_tools.approval_timeout_seconds) for that (org, tool) pair, so every future approval for that tool honors it without the field being passed again. Same clamp rules apply. Customers managing hundreds of tools through the API can set timeouts in bulk this way without using the dashboard. The dashboard still shows the override and "Inherit from org" still clears it.

When you register a tool, oakallow asks you to declare four MCP annotations: read-only, destructive, idempotent, and open-world. These are the same annotations Anthropic's Connector Directory and OpenAI's Apps SDK both require on every tool an AI agent can call. They tell the agent whether the tool mutates data, whether repeat calls are safe, and whether the effects can be undone.

• Read-only: true if the tool only reads or queries (no writes, no side effects).

• Destructive: true if effects cannot be trivially undone (sends email, charges money, deletes records).

• Idempotent: true if repeat calls with the same arguments leave the world in the same state.

• Open-world: true if the tool reaches beyond oakallow to an external system (your backend, Slack, email, etc.).

Oakallow does not vouch for the accuracy of these annotations. We relay what you declared, unchanged, to every MCP client that connects. That is why we ask you to explicitly acknowledge at registration time that the annotations describe the tool accurately. Incorrect annotations can cause an AI agent to misjudge risk: for example, ChatGPT skips confirmation prompts for tools marked read-only, so flagging a write action as read-only would bypass a safety gate. Anthropic's review requires accurate annotations before a connector can be listed in the Directory.

When an MCP client (Cowork, Claude Desktop, ChatGPT, any compatible agent) calls check_permission for a tool name oakallow doesn't recognize for your org, we auto-register it for you. The new tool lands as a draft with default_permission=requires_approval, and you triage it from the dashboard's Tools page under Recently Discovered.

Your agent doesn't have to wait for you. The check_permission call comes back immediately with requires_approval, your agent's tool dispatch creates an approval request, and you handle the actual decision when the notification reaches you. The catalog grows as your agent works, nothing executes without your sign-off.

• Auto-discovered tools come in with conservative annotation defaults — destructive=true, idempotent=false, open-world=true, read-only=false. The semantics of an unknown tool are unknown, so oakallow plants the cautious reading. You adjust them when you review the tool. Until you do, the dashboard shows a needs annotations chip.

• Auto-discovery is MCP-only. The REST permissions check endpoint does NOT auto-create. REST callers manage their catalog explicitly through POST /v1/tools.

• Rate limits prevent runaway. Defaults are 50 auto-creates per hour and 500 lifetime per org, both configurable. When a cap is hit, the verdict is still requires_approval (so the call stays gated) but no new row is added until you triage existing discoveries.

• A tool.auto_created webhook fires on every successful auto-create so you can pipe discovery events to Slack, PagerDuty, or any custom destination.

This is what makes oakallow + Cowork (or any MCP agent) work without pre-registering anything. Connect once, run your agent, triage what shows up.