# Security and authentication

This document describes the currently published customer boundary. It is not a claim of
certification or an expansion of the live feature set.

## Authentication modes

| Client | Credential | Boundary |
| --- | --- | --- |
| Workspace browser | `__Host-cw_session` secure session cookie | Signed-in interactive console |
| Server application | `cw_<environment>_...` Bearer API key | Release-gated `properties:read` access |
| MCP client | Same workspace Bearer API key | Release-gated Streamable HTTP `/mcp` endpoint |

Capabilities, OpenAPI, JSON Schemas, and public examples do not require authentication.
Machine credentials may be used only when runtime capabilities returns
`machine_access.enabled: true`.

## API-key lifecycle

- Keys belong to one workspace and currently carry only `properties:read`.
- The complete secret is returned once. Store it before closing the creation dialog.
- The service stores a SHA-256 hash plus non-secret prefix and usage metadata.
- Keys can be revoked immediately from the workspace console.
- Create a replacement before revoking an in-use key. Test the replacement with a small,
  bounded request, then remove the former secret from every runtime and secret manager.
- Do not share one key across unrelated applications or environments. Separate keys make
  revocation and audit evidence attributable.

## Secret handling

Keep session cookies, API keys, signing secrets, and full webhook bodies out of prompts,
tool arguments, tool results, browser JavaScript, URLs, analytics, support screenshots,
and general application logs. Inject secrets into a trusted server-side adapter from the
deployment platform's secret manager.

Redact `Authorization`, `Cookie`, webhook-signature material, phone numbers, and email
addresses before exporting diagnostic traces. A support request should normally contain
only workspace ID, request or receipt ID, timestamp, endpoint, and stable error code.

## Request protections

- Browser writes require the production origin boundary.
- Machine requests use the `Authorization: Bearer` header, never query parameters.
- Machine search requires `limit`, `max_units`, and `Idempotency-Key`.
- Cross-origin browser requests are rejected when their origin does not match the portal.
- Shared API-key rate limits return `429` and `Retry-After`.
- MCP clients must not pass a token through another tool or downstream service.

## Webhooks

Verify the exact raw body before parsing it. Use `webhook-id`, `webhook-timestamp`, and
every `v1` value in `webhook-signature`. Enforce a timestamp-skew policy, compare HMACs in
constant time, and deduplicate the event ID before executing the business effect.

## Workspace isolation and least privilege

Every authenticated property operation resolves the workspace and its currently entitled,
ready markets. An API key cannot select a different workspace. Do not add acquisition,
administration, destination management, or arbitrary HTTP tools to an agent credential.

## OAuth and enterprise identity

The current machine contract uses revocable workspace API keys. It does not advertise an
OAuth authorization server, dynamic client registration, SSO, or SCIM. Do not publish
OAuth protected-resource metadata until the authorization flow, audience validation,
scope consent, and revocation behavior are implemented and accepted end to end.

## Compliance and reporting

This guide does not assert SOC 2, ISO 27001, GDPR compliance, data residency, penetration
testing, or a numeric availability SLA. Contractual security or processing requirements
must be confirmed through the commercial and legal review process.

Report a suspected security issue privately to `info@cleanedweb.com`. Do not include live
secrets or unnecessary personal data in the first message.