# CapraFeed Access Model

This is the recommended production rollout for commercial API access.

## Account boundary

- A workspace is the billable entity.
- Users can belong to one or more workspaces.
- Billing, quotas, audit history, and API keys attach to the workspace.
- Machine access never reuses dashboard sessions.

## Roles

- `owner`: billing, legal, destructive settings
- `admin`: members, keys, workspace configuration
- `developer`: create and rotate keys, read usage, manage webhooks
- `billing`: invoices, payment methods, tax settings
- `read_only`: usage and contract visibility

## API keys

- Issue keys per workspace and per environment.
- Use clear prefixes such as `cf_test_` and `cf_live_`.
- Reveal each secret once.
- Store only a hash of the secret plus a short display suffix.
- Each key should carry a label, creator, created time, last-used time, optional expiry, optional IP allowlist, and explicit scopes.
- Support overlapping active keys so customers can rotate without downtime.
- Log create, revoke, and failed-auth events.

## Usage and billing

- Map each workspace to one billing customer.
- Start with a base subscription plus one usage meter.
- Meter at the workspace level, not the user level.
- Use entitlements for historical depth, premium support, bulk exports, and reserved endpoints.
- Keep invoices, tax info, payment methods, and cancellation self-serve.

## Authentication split

- Human dashboard auth should use normal browser sessions.
- Programmatic API access should use bearer keys only.
- Do not accept dashboard cookies as machine auth.
- Return a request ID on every response and expose per-key usage in the dashboard.

## Minimum audit trail

- `workspace.created`
- `member.invited`
- `member.role_changed`
- `api_key.created`
- `api_key.revoked`
- `api_key.authentication_failed`
- `billing.plan_changed`
- `billing.payment_failed`