# auth.md

## Audience

This document describes how an automated agent can discover Cascayd resources and request access to protected product APIs. The public marketing site and its discovery documents are readable without credentials.

## Discovery

- Protected resource metadata: https://cascayd.app/.well-known/oauth-protected-resource
- OAuth authorization server metadata: https://cascayd.app/.well-known/oauth-authorization-server
- OpenID Connect metadata: https://cascayd.app/.well-known/openid-configuration
- API documentation: https://cascayd.app/docs/api

## Registration

Agent registration is a manual review flow. Submit a request to https://cascayd.app/agent/auth with the agent name, operator contact, intended Cascayd workspace, requested scope, and redirect URI. Do not include passwords, private keys, or customer data in the request.

The advertised identity type is verified email. A successful registration issues a bearer credential for the approved scope; credentials must be sent in the HTTP Authorization header as `Bearer <token>` and must never be placed in a URL.

## Credential lifecycle

- Claim information: https://cascayd.app/agent/auth/claims
- Revocation: https://cascayd.app/agent/auth/revoke
- Scope currently advertised: `discovery:read`

Agents must request user confirmation before registering, sending data, or using a credential. A 501 response from the registration endpoint means that automated registration is not currently enabled for the requested deployment.