# auth.md

TWIMCO requires no credentials to read its content or to send an introduction.
This document exists so an agent can settle that in one request instead of
probing for a login it will not find.

## Who this is for

Automated clients that read published TWIMCO content, or submit an introduction on
behalf of the person operating them. Everything below is the whole authentication
story for those clients.

## What needs credentials

- **Published content** — `GET https://twimco.com/api/posts` and the other collections in the
  [OpenAPI description](https://twimco.com/api/openapi.json). No credentials, no API key, no registration.
  Unauthenticated requests receive published documents only; drafts are never served.
- **Any page as Markdown** — send `Accept: text/markdown` to a page URL. No credentials.
- **Introductions** — `POST https://twimco.com/api/contact`. No credentials. Rate limited per
  client address. Browser requests must come from this origin; server-to-server
  requests that send no `Origin` header are accepted.
- **Editing** — the CMS at https://twimco.com/admin/ is staff only. Accounts are created by an
  administrator. There is no self-service registration and no agent path into it.

## Registration

There is no agent registration endpoint, and nothing above requires one. Paths such as
`/agent/auth` are not implemented here; do not post to them.

Anything beyond the public surface — higher rate limits, bulk access, a private dataset,
or write access — is arranged with a person:

- Email <hello@twimco.com>
- or use the [contact page](https://twimco.com/contact/)

Say who operates the agent, what it needs to read or write, and the volume you expect.

## OAuth metadata

This service runs no authorization server, so it deliberately does **not** publish
`/.well-known/oauth-protected-resource` or `/.well-known/oauth-authorization-server`.
Those documents would have to name an issuer, a token endpoint and a registration
endpoint that do not exist, and an agent trusting them would fail on the first request.
If TWIMCO ever issues agent credentials, that metadata will be published at those URLs
and named here.

## Identifying yourself

Credentials are not required, but identification is welcome. Send a `User-Agent` that
names the agent and its operator with a contact URL or address, so we can tell a useful
client apart from a scraper and reach you before changing anything that affects you.

Content-use preferences are declared in [robots.txt](https://twimco.com/robots.txt) as Content
Signals, and apply whether or not you authenticate.

## Related documents

- [API catalog](https://twimco.com/.well-known/api-catalog) — RFC 9727 catalog of this site's APIs
- [OpenAPI description](https://twimco.com/api/openapi.json) — endpoints, parameters and schemas
- [Developer documentation](https://twimco.com/developers/) — how to read this site as Markdown or JSON
- [llms.txt](https://twimco.com/llms.txt) — what this site covers and where to read it

## Summary

A summary of this document, not a standards-defined schema:

```json
{
  "resource": "https://twimco.com/api",
  "authentication_required": false,
  "anonymous_read": true,
  "registration_supported": false,
  "registration_contact": "mailto:hello@twimco.com",
  "oauth_protected_resource_metadata": null,
  "oauth_authorization_server_metadata": null,
  "documentation": "https://twimco.com/developers/"
}
```