# auth.md

Sturox Company agent registration and authentication guide.

## Audience

AI agents and automated clients that need to discover Sturox public APIs,
submit a project brief, or register for human review. Owner-only CRM panel
access remains cookie-authenticated for humans and is not issued to agents.

## Registration

- Registration endpoint: `https://sturox.com/crm-api/agent/register`
- Method: `POST` with `Content-Type: application/json`
- Human project brief (browser): `https://sturox.com/start-project/`
- Contact: `hello@sturox.com`

### Example registration request

```json
{
  "agent_name": "example-agent",
  "agent_url": "https://example.com/agent",
  "contact_email": "ops@example.com",
  "purpose": "Discover Sturox services and submit a software brief",
  "scopes": ["agent:discover", "agent:submit-brief"]
}
```

Successful registrations return a pending registration id. Access to private
CRM resources is never granted automatically; Sturox reviews requests manually.

## Supported methods

1. **Anonymous registration** — `POST /crm-api/agent/register` with contact and purpose. Returns a registration id for follow-up.
2. **Verified email follow-up** — reply from the registered contact address when Sturox requests confirmation.
3. **Human-mediated project brief** — submit through `/start-project/` or the public lead form when a person owns the engagement.

## Credentials

- Public discovery and health checks require no credential.
- Public lead and chat intake use anti-abuse controls, not OAuth bearer tokens.
- Bearer tokens are not issued for the owner CRM panel. Panel sessions use an HttpOnly cookie for the verified owner only.

## OAuth discovery

- Authorization server metadata: [https://sturox.com/.well-known/oauth-authorization-server](https://sturox.com/.well-known/oauth-authorization-server)
- OpenID discovery: [https://sturox.com/.well-known/openid-configuration](https://sturox.com/.well-known/openid-configuration)
- Protected resource metadata: [https://sturox.com/.well-known/oauth-protected-resource](https://sturox.com/.well-known/oauth-protected-resource)

## Scopes

| Scope | Meaning |
| --- | --- |
| `agent:discover` | Read public discovery documents, health, and MCP tools |
| `agent:submit-brief` | Submit a project brief / agent registration for human review |

## Related discovery

- API catalog: `https://sturox.com/.well-known/api-catalog`
- MCP server card: `https://sturox.com/.well-known/mcp/server-card.json`
- ARD catalog: `https://sturox.com/.well-known/ai-catalog.json`
- Agent skills: `https://sturox.com/.well-known/agent-skills/index.json`
