# auth.md

How an autonomous agent authenticates with suelo.casa. Short version: for
everything an agent normally wants, it does not have to.

Last reviewed: 2026-09-09.

## The public API needs no credentials

`https://suelo.casa/api/v1` is anonymous, read-only and CORS-open. There is no
registration endpoint, no API key to request and no token to refresh, because
the API returns exactly what an anonymous visitor already sees on the website.
Sending an `Authorization` header changes nothing.

- Catalog: <https://suelo.casa/.well-known/api-catalog>
- Description: <https://suelo.casa/api/v1/openapi.json>
- Documentation: <https://suelo.casa/docs/api> (Spanish) /
  <https://suelo.casa/en/docs/api> (English)
- Health: <https://suelo.casa/api/v1/health>

Identify yourself in `User-Agent`. Responses are edge-cached for five minutes;
polling faster than that returns the same bytes.

## Suelo is not an OAuth authorization server

There is deliberately no `/.well-known/openid-configuration`,
`/.well-known/oauth-authorization-server` or
`/.well-known/oauth-protected-resource` on this domain, and their absence is the
correct answer rather than an omission:

- Human sign-in is delegated to WorkOS AuthKit and produces a session cookie for
  the browser application. It is not a bearer token, it is not issued to third
  parties, and no Suelo endpoint accepts one from an agent.
- The one credentialed endpoint, the partner listing-ingest API, uses a
  bilaterally issued shared secret (see below). No authorization server issues
  it, so there is no issuer to advertise.

Publishing OAuth metadata here would describe endpoints that do not exist. If
that changes, this file and the corresponding `.well-known` documents change
together.

## Signed-in user data is out of scope for agents

Saved searches, favourites, leads, workspaces and the agent dashboard are
reachable only with an interactive WorkOS AuthKit session. There is no delegated
access path for a third-party agent, and impersonating a user's cookie is not
one. If you are an agent acting for a signed-in person, drive their own browser
session rather than asking for credentials.

## Partner listing ingest

`POST /api/ingest/listings` accepts inventory from syndication partners under a
shared secret in `Authorization: Bearer <secret>`.

- Secrets are issued out of band, per partner, after a data agreement. There is
  no self-service registration, and no scanner should attempt one.
- The endpoint is not a general write API and is not appropriate for agents
  acting on behalf of an end user.
- To request access, write to <hola@suelo.casa> describing the source of the
  data, its volume and its update cadence.

## Reporting a problem

Security issues, or a listing whose data looks wrong, go to
<hola@suelo.casa>. Please do not probe registration or ingest endpoints to find
out what they do - this document is the authoritative answer.