What Microsoft Graph permissions we request

When you click "Connect Microsoft 365" you authorize a delegated OAuth grant against your personal Microsoft account. Delegated means the integration can only act on files you have rights to, inheriting your role-based access controls in OneDrive and SharePoint.

What we deliberately do NOT request: Files.ReadWrite or Files.ReadWrite.All (broader read/write outside the app folder), Mail.*, Calendars.*, Directory.*, or any scope that requires tenant-admin consent for broad access. We request Sites.Selected (narrowest possible SharePoint access, opt-in per site by your administrator). We do NOT request Sites.Read.All or Sites.ReadWrite.All which would grant tenant-wide SharePoint access.

Existing connections: connections created before 2026-06-02 still hold the older Files.ReadWrite grant until you reconnect. Visit /account/integrations to apply the narrower scopes today.

About the "app folder" permission

Microsoft's consent screen describes the Files.ReadWrite.AppFolder scope as "Have full access to the application's folder: read, create, update and delete files in the application's folder." This wording sounds broad but the boundary is narrower than it reads.

This boundary is enforced by Microsoft, not by us. Microsoft Graph rejects any request from our access token that tries to read or write outside /Apps/KnowledgeBricks/. We cannot bypass it even if we wanted to. The token simply doesn't grant access elsewhere.

Why we need write access (not just read)

The Files.ReadWrite.AppFolder scope bundles four operations: read, create, update, and delete. Our actual code uses two:

• Create: when you click "Export to OneDrive," we write a markdown file with your Cowork session output
• Update: if you re-export the same session, the file is overwritten in place

We never read files back from the app folder (your browser already has the content) and we never delete files (only you can do that from OneDrive). The read and delete capabilities exist in the scope because Microsoft doesn't offer a write-only or create-only variant, but our code never invokes them.

Verify it yourself. Open OneDrive, navigate to /Apps/KnowledgeBricks/, and you can see exactly what we've written, nothing more. You can rename, move, or delete these files at any time, and you can disconnect the integration to stop further writes.

What we store on our servers

How a file action actually works

1. You click "Attach from OneDrive" inside an engagement.
2. Your browser fetches a fresh access token from our token endpoint, server-side, using the refresh token stored in our database.
3. The browser hands that token directly to Microsoft Graph (graph.microsoft.com) to list folders / files you can see.
4. You pick a file. We store the sharing link and metadata, never the file bytes.
5. When you "Export to OneDrive," the same flow happens in reverse: we generate the document on our server, send it to Microsoft Graph in your name, and Microsoft stores it in your drive. We discard our copy immediately.

At no point is your file content written to KnowledgeBricks's database, object storage, or backups. The exception is the link string itself, which is the same thing you'd paste into an email.

Tenant isolation

Each customer's data is logically separated by Clerk organization ID at every database query. No tenant can see another tenant's documents, engagements, tokens, or audit logs.

Tokens are encrypted at rest using AES-256-GCM with a customer-scoped key derivation. Even if our database were compromised, tokens cannot be replayed without the application key.

What your Microsoft admin can do

• Approve or block the app at the tenant level. Through the Microsoft Entra admin center, under Enterprise applications, your admin can require admin consent for KnowledgeBricks, restrict which users can connect, or block it entirely.
• Revoke at any time. Microsoft tokens are listed in each user's account under "My sign-ins" and then Apps. Revoking there severs the integration immediately.
• Audit every action. Every Graph call shows up in the Microsoft 365 unified audit log with the user's identity, the file touched, and the time. We do not obscure or proxy these calls.

Security practices

• Transport: TLS 1.2+ end-to-end. HSTS with a 2-year max-age + preload is set on every response.
• At rest: AES-256 encryption on the database and on object storage.
• Token storage: Refresh tokens are encrypted with a separate application-layer key.
• Authentication: Clerk (SOC 2 Type II) for user identity. MFA available; SSO supported on enterprise plans.
• Content Security Policy: An enforced CSP is delivered on every page, restricting script execution, frame embedding, and form targets to the declared allow-list. Framing of the portal by third-party sites is blocked (frame-ancestors 'none').
• Hosting: Vercel Functions in US-East. Database hosted on Supabase, US region.
• Backups: Encrypted, retained for 30 days.
• Logging: Error events are scrubbed of request bodies, cookies, and auth headers before leaving the application. No request bodies for the Microsoft Graph proxy are written to logs.
• Dependencies: Automated dependency scanning runs on every pull request and blocks merges on high/critical CVEs. Critical CVEs are patched within 7 days.
• Secret detection: gitleaks scans every commit for accidental credential exposure before merge.

API keys & webhook security

API keys

• We never store your raw API key. At creation time the key is shown once and immediately discarded. Only a SHA-256 hash is written to the database — the raw key cannot be reconstructed from what we store.
• Keys are prefixed kb_live_ and contain 24 bytes of cryptographically random entropy, making offline dictionary attacks computationally infeasible.
• Keys can be assigned an expiry (1 day – 10 years). Expired keys are rejected at the authentication layer before any data access occurs.
• Self-serve rotation is available: creating a replacement key before revoking the old one ensures zero-downtime handoffs.
• Each key has an independent per-minute rate limit (60 req/min by default), enforced atomically in the database.

Webhook signatures

• All outbound webhooks are signed with HMAC-SHA256. The signature is included in an X-KB-Signature header as t=<unix>,v1=<hex>.
• Signatures are verified using constant-time comparison (crypto.timingSafeEqual) to prevent timing side-channels.
• Inbound webhooks from Clerk and Stripe are independently verified against each provider's signing secret before any payload is processed.
• Timestamps are validated within a 5-minute window to reject replayed payloads.

Questionnaire quick-reference

Common vendor security assessment questions answered in one place.

Sub-processors

Roadmap: narrowing the consent further

We agree the Files.ReadWrite scope is broader than ideal. Three changes are in flight:

1. Microsoft Verified Publisher. Application in progress. When approved, the consent screen will show a blue "Verified" badge next to our publisher name.
2. OneDrive / SharePoint File Picker SDK. This replaces the inline file browser. With the Picker, we ask only for Files.Read.Selected on connect, and a per-file token is issued each time you pick a document.
3. Sites.Selected mode for SharePoint. Your admin pre-approves specific sites the integration can touch. Available on enterprise plans alongside Clerk enterprise SSO.

Questions from your security team?

Email security@knowledgebricks.com for:

• Vendor security questionnaires (CAIQ, SIG-Lite)
• Data Processing Addendum (DPA) signature
• Architecture review calls
• Penetration test summary letter
• SOC 2 status update (Type I targeted for 2026 Q4)

For general support questions, please use /contact instead.