How to share API documentation with clients

What usually goes wrong?

The common ways of sharing API docs with a client each break in a predictable place.

• A PDF or a Word file. It is out of date the day after you send it, and you cannot tell which version a client is reading when they report a bug.
• A shared Postman collection. Good for trying calls, weak as documentation: no narrative, no guides, and it drifts from the code too.
• Adding the client to the repository. They get the docs and the code, and probably the issues and pull requests. Most companies do not want that.
• A public docs site. Fine until the docs mention rates, partner-only endpoints or a customer's name.

What you want is one source that stays current, rendered as a site, with a list of who may read it.

Keep the source in the repository

Write the guides as markdown in a docs folder, and commit an OpenAPI file beside them. When the code changes, the docs change in the same pull request, and a reviewer can see both.

DocuGate turns that into a documentation space. Folders become the sidebar. If it finds openapi.json or openapi.yaml in the repository root or the docs folder, it adds an API reference: an overview, a page on authentication, and a page per endpoint with parameters, request body, responses, examples in curl, JavaScript and Python, and a console that sends the call from the reader's browser to your API. The reference is on every plan and sits behind the same gate as the rest of the space.

If your backend already produces a spec, docugate openapi fetches it, removes the paths and fields you do not want shown, and writes a stable file you can commit. See the CLI.

Decide who reads what

Most API owners have more than one audience. A common split:

Audience	Access	Contents
Developers evaluating the API	Public	Quickstart, reference, errors
Clients and partners	Allowlist	Onboarding, SLAs, rate cards, integration specs
Your own team	Repo access	Runbooks, internal procedures

In DocuGate, each of these is a space reading a different folder of the same repository: docs/developers, docs/partners, docs/operations. Each has its own access mode. You write in one place and publish three ways. The logistics industry setup fills this in for you if that is your business.

How does a client sign in?

You add the client's email address, or their GitHub login, to the space's allowlist. The list lives in DocuGate, in the space's settings, and is visible only to you. Entries match without regard to case and there are no wildcards, so *@client.com does not work; name each person.

The client opens the link and signs in with GitHub or with Continue with Google. Google matches their verified address against the list. They do not need a GitHub account, and they never see your repository.

A restricted space they can read shows up under Shared with you on their dashboard, so being added is enough for them to find it again.

When a contract ends, remove the entry. The check runs on the server before any markdown is read, so the next request is refused. A refused reader sees the space's name and a message that the owner has to add them, and nothing else.

Steps

1. Put your guides in a folder such as docs/partners, and commit your OpenAPI file.
2. Sign up with GitHub and open Dashboard → New space.
3. Pick the repository, the branch and the folder.
4. Set access to Allowlist.
5. In the space's settings, add each client's email address.
6. Send them the link.

A public repository works on the free Starter plan. A private one needs Pro, at $5 a month, $50 a year or $2 a week, which also gives unlimited spaces; see pricing.

What about API keys?

Some companies want clients to get an API key from the docs page itself. DocuGate has this on Enterprise, from $29 a month, but it needs the space on your own domain, and custom domains are still in build. Until then, issue keys the way you do today and link to that from the docs.

What DocuGate does not do

It does not show you which client read which page; reader counts and a read audit are not built yet. If per-endpoint analytics are central to how you run your API, a dedicated API docs product such as ReadMe is built for that; see the ReadMe comparison.

Try it

Publish a partners folder as an allowlisted space and add one client's email.