Service Documentation
API Discovery
Machine-readable discovery for the LSO Design Guidelines site lives at `/.well-known/api-catalog`, with the OpenAPI description published at `/openapi.json`.
Published Resources
- API catalog: https://design.lso.com/.well-known/api-catalog
- OpenAPI description: https://design.lso.com/openapi.json
- Health endpoint: https://design.lso.com/api/health
- Agent skills index: https://design.lso.com/.well-known/agent-skills/index.json
- MCP server card: https://design.lso.com/.well-known/mcp/server-card.json
- OAuth authorization server metadata: https://design.lso.com/.well-known/oauth-authorization-server
- Protected resource metadata: https://design.lso.com/.well-known/oauth-protected-resource
- JWKS: https://design.lso.com/.well-known/jwks.json
HTTP Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/health | Health and readiness status for automated discovery. |
| GET | /.well-known/oauth-authorization-server | OAuth 2.0 authorization server metadata for the OTP-backed token flow. |
| GET | /.well-known/openid-configuration | OpenID-style discovery metadata for the same issuer and JWKS. |
| GET | /.well-known/oauth-protected-resource | Protected resource metadata advertising the authorization server and scopes. |
| GET | /.well-known/jwks.json | JWKS containing the public signing key for bearer tokens and ID tokens. |
| POST | /oauth/token | Exchange an email OTP proof for a bearer access token. |
| GET | /oauth/userinfo | Return claims about the authenticated subject for a bearer token. |
| GET | /api/agent/guidelines/business-card | Bearer-protected agent endpoint for the business-card guideline markdown. |
| POST | /api/request-access | Submit a request for access to protected guideline content. |
| POST | /api/send-otp | Send a one-time code to start a credential-based sign-in flow. |
| POST | /api/verify | Verify an OTP and receive a session token payload. |
| GET | /api/approve-access | Admin approval link target used from access-request emails. |
Authentication Notes
The site now publishes OAuth discovery and protected-resource metadata for an OTP-backed bearer-token flow. Clients first call `/api/send-otp`, then exchange the returned `token` and emailed OTP at `/oauth/token` with `grant_type=urn:lso:params:oauth:grant-type:email-otp`. Access tokens are signed with `RS256` and can be validated through the published JWKS.