Question 1

What is oakallow and who is it for?

Accepted Answer

oakallow is a hosted security service for AI agent tool execution. You reach it through the REST API or the MCP connector — same governance, two surfaces.

What it does:

- Checks permissions before your AI agent executes any tool
- Returns a cryptographically signed decision receipt on every check, for auditable proof
- Routes high-risk actions through human approval workflows
- 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. There are two integration paths and you can use either or both.

Shared setup (both paths):

- Create an account on the web at oakallow.io. Sign-in is by passkey or email one-time code, and new accounts receive $5 in free credits.
- Enroll a passkey on your first sign-in. oakallow requires multi-factor authentication on every account.
- Save the 10 recovery codes that are generated automatically when you enroll your first passkey. Store them somewhere safe.
- Register your tools and define permission rules from the dashboard (or skip and let the MCP connector auto-discover them).

REST API path:

- Generate a management API key for setup, then a standard API key for runtime.
- Call the permission check endpoint before your agent acts — it returns a signed decision receipt inline — then log the result.

MCP connector path:

- Add https://api.oakallow.io/mcp as an MCP server in your client (Claude Desktop, ChatGPT, Cowork, or any MCP-compatible agent). OAuth handles auth automatically.
- Your agent calls oakallow tools by name. Unknown tools auto-register as drafts gated on requires_approval.

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

Question 3

Do you have iOS and Android apps?

Accepted Answer

Yes. oakallow has companion apps on the App Store and Google Play. The mobile apps focus on the things you need on the go: signing in with a passkey, reviewing and deciding on approval requests, viewing activity, and managing your organization's credit balance.

What the apps do:

- Sign in with a platform passkey (Face ID, Touch ID, fingerprint, or screen lock)
- Review and approve or deny pending approval requests
- See real-time activity, organization balance, and team status
- Buy credits via Apple In-App Purchase or Google Play Billing

What the apps do not do:

- Account creation. Sign up at oakallow.io on the web.
- Recovery code generation or viewing. Manage recovery codes from the web Security page.
- Configuration of tools, organizations, tenants, or permission rules. Use the web dashboard for setup.

Each mobile install is treated as its own device. The first time you sign in to the app, your passkey is verified through whatever credential authority owns it (iCloud Keychain on iOS, Google Password Manager on Android, or a hardware security key). If you have a passkey on a different device family, sign-in still works using WebAuthn cross-device flow (your phone shows a QR code that you scan with the device that holds the passkey). For everyday convenience, the app may suggest adding a passkey on the current device after your first sign-in.

Question 4

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 (each check returns a signed decision receipt) 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 5

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 6

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 7

How does permission resolution work?

Accepted Answer

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

Gates (checked first):

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

Specificity walk (8 levels, first match wins):

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

Fallbacks (when no rule matches):

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

Question 8

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 9

How do approval workflows work?

Accepted Answer

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, the decision is signed and your agent proceeds.

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 10

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 11

How do Slack notifications work?

Accepted Answer

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.

Once configured, your channel receives a Block Kit card for each approval event:

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

Question 12

How does the PagerDuty integration work?

Accepted Answer

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.

Question 13

What data does Oakallow send to Slack, PagerDuty, or webhooks I configure?

Accepted Answer

Notification payloads are intentionally minimal. Each event contains:

- 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

What we do NOT send:

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

Question 14

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 15

How do two-level approvals work?

Accepted Answer

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.

- Who can do what: directly adding or removing approver-group members on the Team page is open to both admins and owners. Mapping a Microsoft Entra group to an approver group (so membership syncs from your identity provider on each sign-in) is part of SSO configuration and is owner-only. An admin can hand-pick approvers; only an owner can wire an Entra group to a group. See the SSO question for that flow.

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

Question 16

How do approval timeouts work?

Accepted Answer

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.

Question 17

Why does oakallow require MCP annotations on every tool?

Accepted Answer

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.

Question 18

What happens when my agent calls a tool I haven't registered?

Accepted Answer

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.

A few details worth knowing:

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

Question 19

What is a signed decision receipt?

Accepted Answer

A signed decision receipt is a single-use, HMAC-signed proof of what oakallow decided about a tool call.

Every permission check on an approved tool returns a receipt inline, in the same call — for every verdict, not just allowed. There is no separate step: the check that resolves the decision also signs it. The signature binds the verdict and the exact request (tool, tenant, resource, method, parameters), and the receipt carries a nonce that can only be used once, preventing replay.

A receipt is cryptographic evidence that:

- oakallow evaluated this exact request and what it decided (allowed, requires_approval, or disabled)
- The specific tool and parameters were bound to the decision
- The receipt was not reused from a previous call

A disabled receipt is just as real as an allowed one: it is the proof oakallow blocked the action.

(The standalone /v1/tokens/mint endpoint still exists for integrations built before inline signing, but it is no longer required — the permission check signs every decision on its own.)

Question 20

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 21

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 22

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 application backend.
- Internal requests carry signed context such as 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 23

Is multi-factor authentication required?

Accepted Answer

Yes. oakallow is a security platform, so passkey-based MFA is required on every account. There is no opt-out.

How it works:

- You sign in with a passkey, or with an email one-time code if you have not enrolled a passkey yet
- On your first sign-in you are sent to the Security page and asked to enroll a passkey before anything else is unlocked
- 10 single-use recovery codes are generated automatically the first time you enroll a passkey. Save them somewhere safe.
- From then on, every sign-in uses your passkey (Face ID, Touch ID, Windows Hello, fingerprint, or a hardware security key)
- You can add multiple passkeys for different devices, rename them, or remove them from the Security page any time

Why passkeys and not TOTP codes:

- Passkeys are phishing-resistant by design. A fake oakallow page cannot use them.
- No six-digit codes to type, lose, or intercept
- Works identically across iOS, Android, macOS, Windows, and hardware keys
- Syncs through your device ecosystem (iCloud Keychain, Google Password Manager, 1Password, etc.) so a lost phone is rarely catastrophic

A note on cross-platform sync. Passkeys created in Apple devices stay in iCloud Keychain. Passkeys created in Google or Chrome stay in Google Password Manager. The two ecosystems do not sync to each other. If you create a passkey on an iPhone and then try to sign in on an Android phone, sign-in still works through WebAuthn cross-device flow (your Android shows a QR code that you scan with the iPhone), but for daily convenience we recommend enrolling at least one passkey per device family.

If you lose access to every enrolled passkey, see the "What if I lose my passkey?" question below.

Question 24

What are recovery codes and how do I use them?

Accepted Answer

Recovery codes are your backup if you lose access to every enrolled passkey. They are single-use, 26-character codes generated automatically the first time you enroll a passkey on your account. Each account gets 10 codes.

When they are generated:

- Once, automatically, when you enroll your first passkey
- The plaintext is shown to you exactly once. After that we only store a SHA-256 hash, so we cannot show them to you again.
- You can regenerate a fresh batch of 10 from the Security page on the web at any time. Regenerating invalidates every previous code.

How to use them:

- On the Security page, click "Use a recovery code" and enter one
- On success, all of your existing passkeys are invalidated and the code is consumed
- You are signed in temporarily and required to enroll a new passkey before you can do anything else
- The remaining codes still work, but you are down by one

Where to store them:

- A password manager like 1Password, Bitwarden, or Apple Passwords is the most convenient option
- Printed and locked in a safe is fine too
- Do not save them in plain-text files or screenshots on the same device as your passkey. If you lose that device you lose both at once.

If you run out of recovery codes and have lost access to every passkey, contact support@oakallow.io from the email on your account and we will verify ownership and reset your passkey requirement.

Question 25

What if I lose my passkey or need to reset it?

Accepted Answer

You have three recovery paths in order of speed.

Fastest: redeem a recovery code.

- If you saved your 10 recovery codes when you first enrolled a passkey, you can use one to recover
- On the sign-in page, click "Use a recovery code" instead of signing in with a passkey
- Enter your email and one of the codes. On success, all existing passkeys are invalidated and you are required to enroll a new passkey immediately.
- See the recovery codes question above for details

If you have a second passkey on another device:

- Apple. Passkeys stored in iCloud Keychain sync to every device signed into the same Apple ID. If you still have a Mac, iPad, or another iPhone signed in, try signing into oakallow there. The passkey will be available.
- Google. Passkeys in Google Password Manager sync across Chrome on any device signed into the same Google account.
- 1Password, Bitwarden, Dashlane. Passkeys stored in your password manager are available everywhere that manager is installed and unlocked.
- Hardware keys (YubiKey, Titan). Not synced. If the key is lost, use a recovery code or contact support.

If you have access from another device, sign in with that one, then go to the Security page and remove the lost passkey. Add a new passkey on your replacement device from the same page.

Last resort: contact support.

- If you cannot access any enrolled passkey and have no recovery codes left, email support@oakallow.io from the address on your oakallow account
- Include your account email and a brief description of what happened (lost device, wiped phone, hardware key lost, etc.)
- We will verify ownership and reset the passkey requirement so you can sign in with email OTP and enroll a new passkey
- Turnaround is typically under one business day

To make future recovery easier, we strongly recommend enrolling at least two passkeys (for example one on your phone and one on your laptop, or one in a password manager and one on a hardware key) and keeping your recovery codes in a separate location from your devices. You can add additional passkeys any time from the Security page.

Question 26

Where does permission resolution happen?

Accepted Answer

Permission resolution happens at the edge in a Cloudflare Worker.

Permission rules are stored in Cloudflare D1, so when a permission check request arrives, the Worker can resolve it locally without making a round-trip to a separate backend. This delivers very fast decisions and keeps the policy path close to the request path.

The Cloudflare Worker owns the auth and permission surface, while the dashboard and management APIs use the same D1-backed data model, so rule changes stay in sync across the product.

Question 27

What is the infrastructure architecture?

Accepted Answer

oakallow runs entirely on Cloudflare:

- Cloudflare Workers handle authentication, API key verification, permission resolution, token minting, approvals, execution logging, billing, team management, support workflows, and the developer dashboard API.

- Cloudflare Pages serves the developer dashboard, documentation, and marketing site.

- Cloudflare D1 is the shared relational data store for permission and runtime data, and Cloudflare KV is used for fast key lookups, auth caching, and OAuth 2.1 grant storage.

- Cloudflare R2 stores support attachments.

User authentication is native. Passkeys (WebAuthn) and email one-time codes are issued, verified, and stored by oakallow itself, not by a third-party identity provider. Recovery codes are SHA-256 hashed and stored in our database.

The MCP connector (which integrates oakallow with Claude and ChatGPT) is also fully self-hosted. We run our own OAuth 2.1 authorization server on api.oakallow.io using the open-source @cloudflare/workers-oauth-provider library, with PKCE S256 required, refresh-token rotation, dynamic client registration, and a consent screen on our own domain. Compliance details are on our /docs/oauth page.

Supporting services such as Stripe (web billing), Apple StoreKit and Google Play Billing (mobile in-app purchases), Apple Push Notification Service and Firebase Cloud Messaging (mobile push), and Resend (transactional email) plug into that core architecture.

Internal service communication uses signed headers with a 30-second drift window for timing-safe validation where applicable.

Question 28

What OAuth 2.1 standards does the MCP connector implement?

Accepted Answer

The oakallow MCP connector at api.oakallow.io/mcp implements OAuth 2.1 BCP and the MCP Authorization Specification (2025-03-26). PKCE with S256 is required on every authorization, the implicit flow and resource-owner password grant are not accepted, refresh tokens rotate on every use, redirect URIs are exact-matched, and every authorization, token issuance, and revocation is recorded in our audit log.

The full endpoint table, scope descriptions, supported flows, token lifetimes, revocation paths, and per-claim compliance evidence are documented at oakallow.io/docs/oauth. That page is the canonical reference we share with AI-platform review teams when submitting connector listings.

Question 29

What are team roles in oakallow?

Accepted Answer

Every account belongs to a team, and every member of a team has one of three roles. The role controls what the dashboard, the mobile apps, and the API let you do.

Member:

- View organizations, tenants, resources, tools, and permission rules
- View approvals, execution activity, and your own profile
- Cannot create or modify policy data, API keys, settings, billing, SSO, or SCIM

Admin:

- Everything a member can do
- Create and edit organizations, tenants, resources, tools, and permission rules
- Manage API keys and webhook settings
- Configure approver groups for two-level approvals, including adding and removing members directly
- Cannot manage billing, SSO, or SCIM (so an admin cannot map an Entra group to an approver group, since that is part of SSO config)

Owner:

- Everything an admin can do
- Buy credits, view billing history, manage payment methods
- Configure Enterprise SSO and SCIM provisioning, including mapping Entra groups to approver groups
- Manage the Verified Partner Program record for the team
- Promote or demote other members

When you sign up directly, you are the owner of a singleton team you fully control. When you sign in for the first time via your company SSO, you are provisioned just-in-time onto your company team as a member. Your owner can promote you from the Members page.

The role you have is independent of how you sign in. Passkey users and SSO users follow the same role rules and see the same UI for the role they have.

Question 30

What is the Verified Partner Program?

Accepted Answer

The Verified Partner Program is how oakallow lets approvals happen outside the oakallow dashboard, inside a partner's own product, without weakening any of the guarantees that make an oakallow approval trustworthy. We intentionally require partners to register and scope their integration by authority so that a decision made in a partner's own surface carries the same cryptographic execution-token minting, the same immutable audit trail, and the same governance controls as a decision made natively in oakallow.

An authority is a named, domain-verified integration surface registered under a partner's legal entity. A customer opts an authority into their own organization, and from then on approvals in that org can be decided in the partner's product instead of only the oakallow dashboard.

What the program delivers:

- Partners host the human-decision step of an oakallow approval inside their own UI, so their customers approve in the platform they already use while oakallow records the cryptographic decision and the audit trail
- Customers opt in per-org from their own oakallow dashboard. Authority assignments are private to the customer org; there is no public partner directory
- Authorities can use mutual TLS on their callback domain for production traffic
- The partner contact emails (technical and security) receive escalation traffic from oakallow when an authority needs attention

There are two separate attestations, at two levels:

- A parent-partner attestation, made once at apply time, where the applicant attests they are authorized to register this company and corporate domain as a partner. It is recorded with the accepting email, timestamp, and IP.
- A per-authority agreement, accepted separately for each authority registered under the partner. The parent attestation covers the company; the authority agreement covers each individual integration surface.

What verification proves:

- The partner controls the corporate domain they claim, proven with a DNS TXT record on that domain (the Primary Governing Authority domain, or PGA domain). DNS control is the thing we can actually prove, so it is the basis of verification
- The applicant is on the corporate domain (the oakallow account that submits the application must have an email on the PGA domain)
- Each authority independently proves control of its own callback domain with its own DNS TXT record. The callback domain must be a different host from the bare corporate domain, so a partner demonstrates control of the specific surface its approvals run on

Application flow:

1. Apply at oakallow.io/partners/apply from an account whose email is on the corporate domain you submit
2. Attest, at the parent-partner level, that you are authorized to register this company and corporate domain
3. Add a DNS TXT record on the corporate domain to prove you control it
4. Register one or more authorities, each with its own callback domain and its own technical and security contact
5. Each authority proves its own callback domain with a DNS TXT record, verifies its technical and security contacts by email, and accepts the per-authority program agreement
6. Configure mutual TLS for production callback traffic at oakallow.io/partners/mtls-setup

The owner of the verified-partner record is the user who applied, and additional owners can be invited to co-manage the record. Partner dashboard access (oakallow.io/dashboard/partner) is gated on that membership, not on team role, so an owner can manage the record even from a personal oakallow account.

Question 31

How does Enterprise SSO work?

Accepted Answer

Enterprise SSO lets your company sign in to oakallow using your existing identity provider instead of per-user passkeys. The current implementation is Microsoft Entra ID (formerly Azure AD); other providers will follow.

What SSO does:

- Users sign in with their Microsoft account; Microsoft handles the password, MFA, and any conditional-access policy you run. oakallow stores no passwords or MFA secrets — identity is asserted by Microsoft on every sign-in via an id_token.
- New users are just-in-time provisioned on first sign-in: oakallow creates the user, sets team_id to your company team, and assigns the default role (typically member). Later sign-ins update name and last-sign-in only — never role or team.
- Approver group membership is reconciled from Entra group claims on every sign-in, so group changes take effect at the next sign-in.
- Because Microsoft enforces MFA at the IdP, SSO sessions satisfy oakallow's MFA requirement. SSO users are not asked to enroll a passkey or save recovery codes, though the Security page stays available if they want a device passkey for faster local unlock.

How the owner configures it (Account → SSO):

1. Name your team (it appears on the Microsoft consent screen).
2. Enter your Entra tenant ID, application client ID, and client secret.
3. Add your corporate email domains (e.g., islemonics.com) — users on these domains are routed to SSO automatically.
4. Optionally map Entra group object IDs to oakallow approver groups for two-level routing. When you add the mapping you can also give the group a display name, so it shows by name (not just its object ID) here and on the Organizations page.
5. Generate a mobile app code (shown once) and distribute it through your usual internal channel. Rotating it immediately revokes the previous one and forces every device to re-enroll.

SSO configuration is owner-only: the /api/sso-admin/* routes refuse any non-owner caller regardless of how they signed in. This is the one piece of approver-group setup that an admin cannot do. Admins can add and remove approver-group members by hand on the Team page, but mapping an Entra group to an approver group lives under SSO config, so it requires the owner. If an admin is blocked from setting an Entra group, that is expected: the owner needs to create the mapping.

Web sign-in: employees go to oakallow.io, click Sign In, and enter their corporate email. oakallow recognizes the domain and bounces them to Microsoft, which authenticates them (password plus your MFA and conditional-access). They land on the dashboard — no passkey, recovery code, or email-OTP step.

Mobile sign-in (iOS and Android): the app needs to know which SSO config to use without exposing your Entra tenant ID on the public sign-in screen, so the app code is the bridge. Employees install the app, tap "Sign in with company SSO," and paste the app code once per device (stored locally). "Continue with SSO" opens the system browser to Microsoft, which handles MFA and redirects back into the app. If you rotate the code, employees tap "Replace app code" and paste the new value — existing sessions keep working until they expire, but the next fresh sign-in needs the new code.

For your IT welcome doc, include: the app code (a low-sensitivity internal identifier, not a secret — it alone cannot authenticate anyone without your Entra tenant), iOS and Android download links, and a note that the corporate email must already be assigned to the oakallow application in your IdP or sign-in fails at Microsoft with a "not assigned" error.

Seats and deactivation: each SSO config has a seat cap (default 25). Provisioning a brand-new user costs one seat; re-signing an existing member does not. Deactivating a user from the SSO members list 401s their next request, strips them from approver groups, and frees the seat — the team_members row stays for audit history.

Question 32

How does SCIM provisioning work?

Accepted Answer

SCIM 2.0 lets your identity provider create, update, and deactivate oakallow users directly, without waiting for the user to sign in. It complements SSO: SSO authenticates users, SCIM provisions them.

What SCIM does:

- Your IdP (Entra, Okta, Ping, JumpCloud, OneLogin, others) calls oakallow's SCIM endpoints with a bearer token
- When you add someone to the oakallow application assignment in your IdP, the IdP POSTs a Users resource to oakallow and the user appears in the Members list ready to sign in
- When you remove someone, the IdP DELETEs or PATCHes them and oakallow deactivates the row. Their next API request returns 401
- Group memberships sync the same way and feed into approver-group routing

Why SCIM matters:

- Provisioning is decoupled from sign-in. A new hire shows up on Monday and oakallow already knows about them, without waiting for them to click through SSO
- Deprovisioning is decoupled from sign-out. A departing employee is removed from oakallow the moment HR removes them from your IdP, regardless of whether they had an active session
- Audit. Every provisioning event is logged on both sides

How to set it up:

1. The team owner opens Account, then SCIM, in the dashboard
2. Generate a SCIM bearer token. The token is shown once. Store it in your IdP's credential store
3. Copy the SCIM base URL shown on the page
4. In your IdP, create or configure the oakallow application with provisioning enabled. Paste the base URL and bearer token
5. Assign users and groups to the application. The first provisioning cycle creates the rows

SCIM configuration is owner-only. SSO and SCIM use independent credentials, so you can adopt them separately or together.

Question 33

What is an agent identity?

Accepted Answer

An agent identity gives an autonomous AI agent, one that runs on its own with no person in the loop, its own named identity in oakallow instead of sharing one connector login with every other agent. The point is visibility and a clean record: each agent acts under its own name, its activity is attributed to it in the audit trail, and when an action needs a person, the approval stays a clear, separate human step.

What an agent identity is:

- Its own credential. The agent authenticates with a token the way a service makes an API call, no human inbox and no interactive sign-in.
- Attributed activity. Every permission check the agent makes is recorded under that agent by name, so you can tell your agents apart instead of collapsing them into one shared account.
- A clear human approval step. An agent can submit and check requests; it can never approve, not its own and not anyone else's. The approver is always a separate person.

Where it is scoped and how it behaves:

- Scoped to one organization, chosen when you create the agent. Its whole surface is that org's already-approved tools.
- It can check permissions, submit gated requests, and check the status of its own requests. It cannot read org settings, team, or billing.
- Rate-limited per identity, can carry an expiry, and is revoked instantly from the dashboard. Only a SHA-256 hash of the token is stored; the raw token is shown once on creation.
- Provisioned by a person. Only an owner or admin can create an agent, so a human is accountable for it from day one.

A person using an AI assistant does not need an agent identity: they sign in as themselves, so the action is already attributed to them. Agent identities are for the autonomous case. See oakallow.io/info/agents for the full model.

Question 34

How do I connect an autonomous agent?

Accepted Answer

An autonomous agent connects to the same MCP endpoint as a human-driven client, it just presents its own token instead of going through the interactive OAuth flow. There is no consent screen and no sign-in.

Steps:

1. Provision the agent. In the dashboard, open Account, then Agents, and create an agent (owner or admin only). You give it a name and pick the one organization it acts in.
2. Copy its token. oakallow returns an oak_agent_ token once, on creation, and stores only a SHA-256 hash. Put it straight into your agent's secret store; if you lose it, rotate the agent for a new one.
3. Point the agent at the endpoint. Your agent authenticates to api.oakallow.io/mcp with the header Authorization: Bearer oak_agent_... The /mcp handler checks for an oak_agent_ bearer before the OAuth provider, so the two credential types share one endpoint.
4. Register and gate your tools as usual, then watch the first approval land under the agent's name.

What the agent can and cannot do:

- On connect it has the same four read-only oakallow tools, scoped to its org: check_permission and list_my_tools (its org's approved tools only), list_pending_approvals (only its own requests), and check_approval_status.
- It can submit and check permission requests but can never approve, and it cannot reach org settings, team, or billing.
- It is rate-limited on its own identity, so one agent never crowds out another.

A person provisions the agent and a person still approves the actions that need a human. See oakallow.io/info/agents for the model.

Question 35

How does billing work?

Accepted Answer

oakallow uses a prepaid credit model. Credits belong to your organization, not to individual user accounts — every team member who has owner-level access can fund the org, and every billable API call deducts from the org's balance.

You purchase credits via Stripe on the web, or via Apple In-App Purchase or Google Play Billing in the mobile apps. Credits are consumed by billable API calls at $0.005 per call. New accounts get a default organization seeded with $5.00 in free credits, which expire after 30 days.

Credit packages:

- Starter: $9.99 for $10 in credits
- Builder: $24.99 for $25 in credits
- Growth: $49.99 for $50 in credits, plus a $2.50 bonus
- Scale: $99.99 for $100 in credits, plus a $10 bonus

When your organization's balance reaches zero, billable API calls against that organization are rejected until an owner adds more credits (or until the org has opted into team-pool fallback, in which case the team pool covers the overrun). Management operations are always free regardless of balance.

Question 36

Can I delete my account?

Accepted Answer

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

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

Get the mobile app

Ready to get started?