How to Write a Trust Page (and Add security.txt)
Developers adopt your API. Then someone at their company has to approve it. That person opens your site, looks for a page called "Security" or "Trust," and decides in a few minutes whether you look like a vendor that takes this seriously.
If that page doesn't exist, they email you a questionnaire. If it exists and is vague, they email you a questionnaire and trust you less. If it's clear and specific, many of their questions are already answered.
This guide covers how to write a trust page for a small dev-tool or
API company, and how to publish a correct security.txt file
alongside it.
What a trust page is for
A trust page has three readers: the security reviewer, who wants specifics; the developer champion, who wants a link to forward internally; and the security researcher, who wants a contact address, fast. Write for all three.
The one rule: only publish what is true today
A trust page is a public statement about your company. Everything on it should be true now, not planned. Put roadmap items in a clearly labeled "What's next" section with honest wording. Don't display a compliance badge or framework name you haven't earned, and don't describe a cloud provider's certifications as if they were yours.
Structure that works
Use this order. Each section is short.
1. Summary (three to five sentences)
Who owns security, what you protect, and how to reach you.
Security at [Product] is owned by our CTO. We store customer API payloads for [N] days in [region], encrypted at rest and in transit. We do not currently hold a SOC 2 report; this page describes the controls we operate today. Questions: [email protected].
2. Infrastructure and hosting
- Where you run (cloud provider, regions).
- What you inherit from the provider (physical security, hardware) versus what you run yourself (application, access, configuration).
- Link to the provider's public compliance page so reviewers can check it directly.
3. Data handling
This is the section reviewers read most carefully.
| Topic | What to write |
|---|---|
| What data you collect | List categories: account info, API request metadata, payloads (if stored). |
| Where it lives | Region(s), data stores. |
| Encryption | In transit (TLS version policy), at rest (what's encrypted and how keys are managed). |
| Retention | How long each category is kept. |
| Deletion | How a customer requests deletion, and how long it takes. |
| Subprocessors | Link to a list of third parties that touch customer data and why. |
Be concrete. "We take data protection seriously" says nothing. "Request payloads are deleted after 30 days; account data is deleted within 30 days of account closure" says something.
4. Access control
- MFA or SSO enforced on production systems and source control.
- Who has production access (by role, not name) and how often that list is reviewed.
- How access is removed when someone leaves.
5. Application security
- Code review required on every change.
- Dependency and container scanning in CI.
- How you handle secrets (a secrets manager, never in source).
- Third-party penetration testing: say whether you've done it. If not, say "not yet."
6. Availability and incident response
- Link to your status page.
- How you notify customers of an incident that affects their data, and through which channel.
- Backup frequency and whether restores are tested.
7. Compliance
State exactly where you are. Good examples:
- "We have not completed a SOC 2 examination. We can share our security overview and evidence under NDA."
- "We support data processing agreements on request."
8. Vulnerability disclosure
A short policy: how to report, what's in scope, what researchers
should not do, and that good-faith research is welcome. Link to your
security.txt.
9. Documents on request and last updated
List what a reviewer can get under NDA (security overview, architecture diagram, incident response plan).
A date at the bottom. Review the page quarterly and change the date only when you actually reviewed it.
Writing the vulnerability disclosure policy
You don't need to invent this. CISA publishes a vulnerability disclosure policy template written for U.S. federal agencies, and its structure adapts well to a small company:
- Authorization. A statement that good-faith research following the policy is welcome. Have a lawyer review this section for your situation.
- Guidelines. Researchers should report promptly, avoid privacy violations and service disruption, use exploits only to confirm a vulnerability, and give you reasonable time before public disclosure.
- Test methods not allowed. Denial of service, physical testing, social engineering.
- Scope. Which domains and services are in scope, and which aren't (for example, third-party services you use).
- How to report. A form or address, what to include (location, impact, reproduction steps), and how quickly you'll acknowledge.
Keep the promises you make. If you say you'll acknowledge reports within three business days, set up the alerting to make that true.
Adding security.txt (RFC 9116)
security.txt is a small plain-text file, defined in RFC
9116, that tells researchers how to reach you. It's a few minutes of
work and reviewers notice it.
Where it goes
Serve it at:
https://example.com/.well-known/security.txtThe RFC requires the file to live under the
/.well-known/ path and to be served over HTTPS, as
text/plain with a UTF-8 charset. A copy at the site root is
allowed for legacy compatibility, but the /.well-known/
version takes precedence.
Required fields
Two fields are required:
- Contact. At least one, and you can list several in
order of preference. Use
mailto:for email,tel:for phone, or anhttps://URL for a web form. - Expires. Exactly once. A date and time in RFC 3339 format after which the file should be considered stale. The RFC recommends setting it less than a year into the future.
Everything else is optional.
Useful optional fields
- Policy. Link to your vulnerability disclosure policy.
- Encryption. A URL to your public key, if you accept encrypted reports. The key itself does not go in the file.
- Acknowledgments. Link to a page thanking researchers.
- Preferred-Languages. Languages you accept reports in.
- Canonical. The URL(s) where this file is meant to live.
- Hiring. Link to security job openings.
A minimal, correct example
Contact: mailto:[email protected]
Contact: https://example.com/security/report
Expires: 2027-09-30T23:59:59Z
Policy: https://example.com/security/disclosure-policy
Preferred-Languages: en
Canonical: https://example.com/.well-known/security.txtThe RFC also recommends signing the file with an OpenPGP cleartext signature. If you don't have a key-management process yet, ship the unsigned file first and add signing later.
Don't let it go stale
The Expires field exists because outdated contact info
sends reports to the wrong place. Put a calendar reminder a month before
the expiry date. When you rotate the security inbox, update the file the
same day. Check it into your repo so it goes through the same review as
everything else.
Verify after deploy (some static build tools skip dot-folders):
curl -sI https://example.com/.well-known/security.txt
should return 200 and text/plain; charset=utf-8.
Checklist
Do this next
The Security Review Kit includes a fill-in trust page template, a disclosure policy outline and a security.txt starter, written for small dev-tool teams. It's also part of the Developer Launch Kit Complete bundle. Get the Security Review Kit: https://shiptodevs.com/#security-review
Sources
- RFC 9116, A File Format to Aid in Security Vulnerability Disclosure: https://www.rfc-editor.org/rfc/rfc9116
- CISA, Vulnerability Disclosure Policy Template: https://www.cisa.gov/vulnerability-disclosure-policy-template
- AICPA & CIMA, System and Organization Controls: SOC Suite of Services: https://www.aicpa-cima.com/resources/landing/system-and-organization-controls-soc-suite-of-services
The Security Review Kit: the full method as templates, a worked example and agent skills.