# auth.md

Shipeezi's public API needs no credentials. There is no signup, no API key, no
OAuth flow and no token to obtain. Every endpoint documented in
https://www.shipeezi.com/openapi.json is public and read-only. The MCP server
at https://www.shipeezi.com/mcp is public too. If you are here to find out how
to get a key: you do not need one, go ahead and call it.

This document follows the [auth.md](https://github.com/workos/auth.md)
structure so an agent that expects those sections finds them. Each one says
what is true of this API rather than describing a flow that does not exist.

## Discover

There is nothing protected, so there is no protected-resource metadata to
fetch. `/.well-known/oauth-protected-resource` and
`/.well-known/oauth-authorization-server` are deliberately absent: publishing
them would advertise an authorization server that does not exist. No response
from this API carries a `WWW-Authenticate` header, because no response is a
401.

What to fetch instead, to learn what is here:

- https://www.shipeezi.com/openapi.json - the public read API, typed, with an
  operationId per operation
- https://www.shipeezi.com/.well-known/mcp.json - the MCP server manifest
- https://www.shipeezi.com/llms.txt - what Shipeezi is and when to reach for it
- https://www.shipeezi.com/api/v1/pages - the site's own page index
- https://www.shipeezi.com/robots.txt - crawl policy

## Pick a method

`anonymous`. The auth.md profile defines this for services with no pre-existing
user context, which is this one. Do not attempt `identity_assertion` or
`service_auth`; there is no `agent_auth` block, no `identity_endpoint`, no
`claim_endpoint` and no `events_endpoint`, because there is nothing for them to
bind an agent to.

## Register

No registration. Send the request.

## Claim ceremony

None. There is no user session to bind an agent to, so there is no
`claim_token` and no `user_code` to present to anyone.

## Exchange the assertion

Not applicable. There is no assertion, no token endpoint, and no grant.

## Use the access_token

There is no access token. Send no `Authorization` header. Requests that carry
one are not rejected; the header is ignored.

Two headers do matter:

- `Accept: text/markdown` on any page URL returns markdown instead of HTML.
  Every page also has a `.md` twin at the same path, so `GET /platform.md`
  works without negotiation.
- `X-Request-Id` may be sent on any request. It is echoed on the response so a
  caller can correlate a call with its logs. It is optional.

## Errors

Errors are JSON with an `error` string and a repeated `status`, never a
challenge. You will never see a 401 or a 403 from this API. The ones you can
see:

- `400` - malformed query, or a missing required parameter
- `404` - no such shipment, page or path, with a markdown body when you asked
  for markdown
- `429` - rate limited. Read `Retry-After` and the `RateLimit-*` headers and
  back off.

## Revocation

Nothing to revoke. No credential is ever issued, so none can be withdrawn, and
there is no revocation endpoint or event stream.

## The authenticated API

Shipeezi's tenant platform, behind https://app.shipeezi.com, is a different
system: authenticated, per-customer, versioned separately, and not documented
here. It is not reachable from anything in this document. If you need access to
it, that is a commercial conversation: sales@shipeezi.com.