Spaces, Sharing & Permissions

Everything your organization puts into Honeycomb — documents, memories, facts, insights — lives inside a Space: a container of related knowledge with its own audience. Spaces are how a single memory store safely serves your whole company: your CEO's email threads, a public Slack channel, and a sales rep's private notes coexist in one corpus, and every read returns only what the caller is allowed to see.

This page covers the access model end to end: what Spaces are, how content is placed into them at ingest, how to share and revoke access, how to widen visibility deliberately, and how agents read on behalf of specific people.

At a glance

• Everything lives in a Space. A channel, an email thread, one person's private context, a research workspace, or the single org-wide Space.
• The golden rule: a record is visible to you if it belongs to an org-public Space or a Space you've been explicitly granted. There is no third path.
• Private by default. Ingest never guesses upward — content with ambiguous provenance lands in a private quarantine Space, not the org-wide one.
• Sharing is live, not a copy. A share grants real access to the Space itself; the recipient sees new content as it flows in, and a revoke ends it everywhere at once.
• Revocations stick. Removing someone survives connector re-deliveries and re-ingestion — access never silently comes back.
• Sensitivity has a ceiling. Confidential or restricted content can never be promoted to org-public, no matter who asks.

What a Space is

A Space groups records that share an audience. Every record belongs to a Space from the moment it's ingested, and the Space — not the record — carries who can read it. Space ids are deterministic and human-readable, so you'll recognize them in API responses: space:acme:email-thread:thr_8231 is always the same thread.

The golden rule: who can see what

Every read — Search & Recall, Ask, the MCP tools, the console — applies the same server-side rule:

This is enforced on every request, in both the database and the search index, from the same grant set. There is no client-side flag that widens visibility, and retrieval scopes like spaceId or threadId can only narrow results within what you already have access to.

Note: records outside your view return 404, never 403 — the API doesn't confirm the existence of things you can't see.

What "org-wide" means

"Org-wide" means everyone on your workspace roster — the members of your organization — not merely anyone who shares your memory store. That distinction matters when your store also holds external identities: a customer who corresponds with you has their own private context in your store, but they are not a member of your workspace, and org-wide knowledge must never fall into their view.

So org-wide content isn't left open to "any identity in the tenant." It lives in a members Space whose grant list is your workspace roster: members hold a grant and see it; external and guest identities hold none and are excluded. Your roster drives that grant list automatically — inviting a teammate grants them org-wide access, and removing them ends it — so "everyone in your org" always means exactly your current members.

How ingest places content — private by default

At ingest, Honeycomb inspects each document's provenance and routes it to exactly one Space. The rules run top to bottom; the first match wins:

Three properties are worth internalizing:

• Only two routes ever produce org-wide visibility — an explicit orgWide: true opt-in, or a channel the connector marks as public. Nothing defaults upward.
• A bare display name never claims a personal Space. Two people named "Sam Lee" must never collapse into one private context, so weakly-identified content goes to quarantine instead. Strong identity means an email address or a platform login.
• A spaceId that doesn't exist is ignored, not an error. The document falls back to the provenance rules above — never dropped, never leaked.

Derived knowledge inherits access

Memories, facts, and relationships extracted from a document inherit that document's Space automatically. When a derived record (like a mined insight) draws on multiple sources, it takes the most restrictive intersection of their audiences — and if that intersection is empty, it stays hidden rather than leak a private source into a wider audience.

Sharing

Sharing grants a teammate live access to a Space you own. It's a real grant, not a copy: they see the Space's content in their own searches and Ask sessions immediately, including content that arrives after the share.

Roles

Only a Space's owner (or someone granted the owner role) can share it. One person's personal Space is never widened by automation — sharing it is always a deliberate act by its owner or an org admin, and every share records who made it.

Share a Space

POST /api/v1/spaces/:id/shares — share by email; Honeycomb resolves it to the person's canonical identity so the grant works everywhere they show up.

curl -s -X POST "$HONEYCOMB_URL/api/v1/spaces/space:acme:email-thread:thr_8231/shares" \
  -H "Authorization: Bearer hck_..." \
  -H "x-acting-user: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "role": "reader" }'

Success is 204. The x-acting-user header identifies who is doing the sharing — sharing always requires an acting user, and that user must own the Space.

Share a single document's context

If you have a document id rather than a Space id, POST /api/v1/entries/:id/share resolves the document's Space and shares that:

curl -s -X POST "$HONEYCOMB_URL/api/v1/entries/ke_42/share" \
  -H "Authorization: Bearer hck_..." \
  -H "x-acting-user: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

{ "shared": true, "spaceId": "space:acme:email-thread:thr_8231", "principalId": "per_31fa9c" }

Note that this shares the document's whole Space — the full thread's context, not one message in isolation. That's deliberate: memory without its context is misleading.

Revoking

DELETE /api/v1/spaces/:id/shares/:principalId — the path segment accepts an email or a principal id:

curl -s -X DELETE "$HONEYCOMB_URL/api/v1/spaces/space:acme:email-thread:thr_8231/shares/[email protected]" \
  -H "Authorization: Bearer hck_..." \
  -H "x-acting-user: [email protected]"

Success is 204, and it takes effect on the very next read. A Space owner can revoke anyone; anyone can always revoke their own access to a Space that was shared with them.

Note: revocations stick. Connectors re-deliver and re-process content continuously, and ingest re-runs its placement rules each time. A revoked person stays revoked through all of it — mechanical re-ingestion never restores access. Only a new, deliberate share brings them back.

Seeing your shares

Two listing endpoints keep both directions visible. Each returns up to 200 entries, newest first, and requires an x-acting-user:

curl -s "$HONEYCOMB_URL/api/v1/spaces/shared-with-me" \
  -H "Authorization: Bearer hck_..." \
  -H "x-acting-user: [email protected]"

{
  "shares": [
    {
      "spaceId": "space:acme:email-thread:thr_8231",
      "kind": "email-thread",
      "label": null,
      "visibility": "private",
      "role": "reader",
      "sharedBy": "per_a41b02",
      "sharedByLabel": "Priya Nair",
      "ownerLabel": "Priya Nair",
      "sharedAt": "2026-07-07T12:00:00.000Z"
    }
  ]
}

Who can see this

Because a single answer can weave together a public channel post, a shared thread, and one of your own private notes, Honeycomb makes the audience of each piece visible rather than leaving you to guess.

Every source behind an Ask answer is tagged with its visibility, so a private source is clearly marked as restricted rather than blending in with org-wide ones. In the Lua desktop app this surfaces as an Org / Private marker on each cited source, plus a footer note when an answer draws on anything private — a reminder that some of what you're seeing isn't visible to everyone.

For any Space you can already see, you can list exactly who else can:

GET /api/v1/spaces/:id/grants returns the Space's roster with human-readable labels:

curl -s "$HONEYCOMB_URL/api/v1/spaces/space:acme:email-thread:thr_8231/grants" \
  -H "Authorization: Bearer hck_..." \
  -H "x-acting-user: [email protected]"

{
  "space": { "id": "space:acme:email-thread:thr_8231", "kind": "email-thread", "visibility": "private" },
  "ownerLabel": "Priya Nair",
  "grants": [
    { "principalId": "per_a41b02", "label": "Priya Nair", "role": "owner" },
    { "principalId": "per_31fa9c", "label": "Sam Lee", "role": "reader" }
  ]
}

This read is itself access-scoped: it answers only for Spaces the caller can already see. Ask for a Space you have no visibility into and it returns 404, exactly like any other read — the roster never becomes a way to probe for Spaces you can't access.

Promotion: widening visibility deliberately

Sharing adds individuals. Promotion makes a whole Space readable by everyone in your organization. Because that's a bigger step, it's a two-party flow — an owner requests, an org admin approves:

While a Space is pending-public it remains fully private — nothing opens up until the approval lands. Approvals happen in the console (see below). And visibility never moves downward on its own: re-ingesting a source never demotes a Space that was promoted.

The sensitivity ceiling

Every piece of content is automatically classified for sensitivity at ingest, and each Space carries the high-water mark of everything inside it:

A Space whose ceiling has reached confidential or restricted cannot be promoted to org-public — the request is refused at multiple independent layers, and no role or console action overrides it. You can still share such a Space with specific people; you just can't open it to everyone.

Consent scope: what insights may learn from

Separate from who can read, each memory carries a consent scope (personal, team, or org) that gates what org-wide insight mining may learn from. Personal-origin memories — DMs, private notes — are excluded from org-wide mining until their owner opts them in:

curl -s -X PATCH "$HONEYCOMB_URL/api/v1/memories/m_204/promote" \
  -H "Authorization: Bearer hck_..." \
  -H "Content-Type: application/json" \
  -d '{ "scope": "org" }'

{ "ok": true, "consentScope": "org" }

Consent promotion is one-way (personal to team to org); attempting to move down returns 409. It does not change who can read the memory — that's still governed by its Space.

Acting on behalf of users

When your backend or agent serves many humans through one API key, tell Honeycomb whose view to use:

curl -s "$HONEYCOMB_URL/api/v1/search" \
  -H "Authorization: Bearer hck_..." \
  -H "x-acting-user: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{ "query": "renewal terms we discussed with Meridian" }'

• Reads narrow to that person's view: org-public content plus the Spaces they've been granted.
• The header only works for trusted keys. x-acting-user is honored only when your API key was issued with the act-as-user capability. On any other key it's ignored — and the request falls back to org-public content only, never to everything.
• No acting user means org-public only. An absent or unrecognized user never widens a read.
• Sharing requires an acting user, since the actor must be the Space's owner.

Agents connected over MCP get the same behavior: the read tools honeycomb_search, honeycomb_recall, and honeycomb_context run in the acting user's view, while honeycomb_ingest, honeycomb_upload, and honeycomb_manage handle writes and administration. See Agents & MCP.

Managing access in the console

Org admins get a full picture in the web console:

1. Open Admin & Access and select the Access tab. Every Space in your org is listed with its kind, visibility, owner, grants, and content count.
2. Add or remove people on any Space by email — the same grants the API manages.
3. Change a Space's visibility here, including approving or rejecting pending-public promotion requests.
4. For a single document, use Sources → Documents and the share context action on any document's detail view.

API quick reference

All endpoints use Authorization: Bearer hck_...; the Acting user column shows which also require an x-acting-user header.

Common errors

Where to next

• Identities & approvals — how a grant to an email reaches the right person, and the approval that guards access-bearing email links.
• Ingesting Data — the spaceId, orgWide, and audience metadata that drive placement.
• Search & Recall — how scoped retrieval behaves inside this model.
• Agents & MCP — wiring acting users into agent sessions.
• Security — organization isolation, key handling, and the wider trust model.