---
title: Private docs
description: What to do when your documentation is not meant for the public — what Docsary can enforce today, what it cannot, and the architecture we recommend for internal, team, and agent-only docs.
order: 7
---

# Private docs

Not every manual is public. Internal runbooks, customer-specific deployment notes, an
architecture reference an agent fleet reads but nobody blogs about — these need a different
answer than a docs site with a sitemap.

This page is deliberate about the difference between *unadvertised* and *private*, because
confusing the two is how internal documentation ends up in a search index.

## Where things stand today

**Every Docsary site is public.** A site answers to anyone who requests one of its addresses.
There is no password, no login, and no per-reader access control. Treat any page you push as
world-readable the moment it exists.

A few things people reasonably mistake for privacy, and what they actually buy you:

| Approach | What it actually does |
| --- | --- |
| Not linking to a page | Nothing. The navigation, sitemap, and full-text index all list it. |
| Not attaching a custom domain | Nothing. The site still answers on its `docsary.com` address. |
| Keeping a version out of the default | Nothing. Non-default versions serve under their own slug. |
| Robots and AI-crawler directives | Keeps well-behaved crawlers out of an index. It is not access control — the page still answers every request. |

None of these is a security boundary. They reduce discovery, not access.

## What works today: keep it out of the browser entirely

If your readers are **agents, scripts, or CI** — which is a large share of internal
documentation — you do not need a public page at all. Docsary's API requires an API key for
every read, so the API *is* a private surface today.

Provision a **read-only key** for the consumer, and let it fetch the content directly:

```bash
# a whole version, as the markdown you pushed
curl -H "Authorization: Bearer $DOCSARY_READ_KEY" \
  https://api.docsary.com/v1/sites/acme/versions/1.0/export

# or one page
curl -H "Authorization: Bearer $DOCSARY_READ_KEY" \
  https://api.docsary.com/v1/sites/acme/versions/1.0/pages/runbooks/failover
```

A read-only key cannot write, cannot reach another organization's content, and can be revoked
without touching the key your pipeline pushes with. For an agent team sharing a private
knowledge base, this is the recommended pattern today — the docs live in one place, every
reader authenticates, and nothing is ever served to an anonymous request.

The tradeoff is that this gives you content, not a website: no rendered pages, no navigation,
no search UI. For humans who want to read in a browser, see the next section.

## Putting your own gate in front

The instinct to front the site with your own access layer — an identity-aware proxy, a VPN, an
SSO gateway — is a good one, and it is the model we intend to support. Your identity provider,
your rules, no new login for your team to learn.

**Be aware of the gap before you rely on it today.** A gate in front of your hostname controls
the path *through your gate*. It does not stop a request that skips it: your site also answers
on its `docsary.com` address, and a request presenting your hostname directly to our servers
never passes through your infrastructure at all. Today, a gate in front of a Docsary site is a
speed bump for casual traffic, not a boundary an attacker respects.

Closing that gap needs enforcement at our end, which is what we are building.

## What is coming: private mode

A per-site setting that turns the arrangement above into a real perimeter:

- **No public address.** No `docsary.com` address is published for the site, and the ones it has can be withdrawn.
- **Out of every index.** Excluded from sitemaps, robots directives, the AI-readable listings, and search-engine surfaces entirely.
- **Never shared-cached.** Responses are marked private, so no shared cache holds a copy.
- **Every request must prove it belongs.** A private site answers only requests carrying either a read-only API key, or a shared secret header that your own gate injects. Anything else gets a 404 — including a request that presents your hostname directly.

That last point is the one that matters: it is what makes "put it behind our SSO" true rather
than decorative, and it works with whatever identity system you already run, because we never
see it. Your gate authenticates the human; the header proves the request came through your gate.

Hosted logins — magic links, email-domain allowlists, SSO connectors — are not on the roadmap.
If that is what you need, tell us; we would rather build it for a customer who wants it than
guess at it.

## Recommendations, in short

- **Agent or machine readers:** use the API with a read-only key. Private today, no waiting.
- **Human readers, sensitive content:** wait for private mode, or host that content somewhere with an access model today. Do not rely on an unlisted address.
- **Human readers, merely unadvertised content:** a normal site with crawlers and AI listings turned off is fine — as long as everyone involved understands the page still answers anyone who asks.
- **Everyone:** never put credentials, keys, or personal data in documentation, whatever the access model. Docs get copied, exported, and pasted into chat windows.

Ask us if your situation is not covered here. See [Access](/access) for how keys and
organizations are provisioned.