# Vindur Auth Guide

Vindur public discovery endpoints are intentionally zero-auth.

## Discover

Agents can discover the public API through [OpenAPI](https://vindur.app/openapi.json), [API catalog](https://vindur.app/.well-known/api-catalog), [developer docs](https://vindur.app/developers), and [OAuth Protected Resource Metadata](https://vindur.app/.well-known/oauth-protected-resource).

## Pick A Method

Use the zero-auth public method for `public.read` operations. OAuth, API keys, client secrets, PKCE, and paid registration are not required for reading public sanctuary data.

## Register

No registration is required. Agents that require a registration-shaped response may call `GET https://vindur.app/agent/auth/register`, which returns a zero-auth `public-zero-auth` client descriptor.

## Claim

No credential claim is needed. Treat `public.read` as already granted for public endpoints.

## Use Credential

Do not send a bearer token for public endpoints. If a client sends one, Vindur ignores it for public reads. Private endpoints return `authentication_required` and include `WWW-Authenticate` metadata.

## Errors

- `authentication_required`: private user data is not exposed through the public API.
- `invalid_token`: any provided private bearer token is invalid for private surfaces.
- `api_route_not_found`: the requested API route does not exist.
- `rate_limited`: retry with exponential backoff starting at 2 seconds.
- `invalid_batch`: batch request shape is invalid.
- `spot_not_found`: the requested public sanctuary id or slug was not found.
- `method_not_allowed`: use the documented HTTP method.

## Revocation

There is no public credential to revoke. To stop using Vindur public data, stop calling the public endpoints. Private user sessions are managed only inside the Vindur web app via Firebase.

## Public API

- No API key required.
- No OAuth token required.
- No paid plan or self-serve key setup required.
- CORS is enabled for public read endpoints.

## Private Surfaces

User profiles, bookmarks, admin dashboard and account-specific write actions are not exposed through the public API. Browser app authentication remains handled by Firebase for user-facing app flows.

## Agent Guidance

Agents should use these public resources first:

- [OpenAPI](https://vindur.app/openapi.json)
- [API Reference](https://vindur.app/api-reference)
- [llms.txt](https://vindur.app/llms.txt)
- [llms-full.txt](https://vindur.app/llms-full.txt)

If an agent needs private user data, it must ask the user to use the Vindur web UI directly. Do not infer or request private account credentials.