HowAISafe separates submitted evidence, reviewer acceptance and legal or certification conclusions. This reference documents the behavior that exists now.
Owner/Admin: manage members, settings, tokens and evidence deletion. Contributor: registers systems and submits evidence. Reviewer: accepts submitted evidence. Viewer: read-only access.
When strict review is enabled, the submitting user cannot accept the same control.
PDF, PNG, JPEG, TXT, CSV and JSON files up to 8 MB are accepted. The service validates basic file signatures, stores a SHA-256 digest, versions matching filenames and serves files as downloads.
Automated malware scanning and external object storage are not connected. Do not upload secrets or raw production datasets.
Missing has no accepted evidence. In progress is assigned work. Ready for review records the submitter. Accepted records the reviewer and time. Not applicable records an operator decision.
Optimistic revisions reject stale browser updates instead of silently overwriting newer work.
The workspace opens on Today: how much of your AI estate is evidenced, high-risk systems live without full evidence, controls waiting for review, overdue controls, and today's three moves.
Each AI system has its own page that walks it Register → Evidence → Review → Approved. Per control: Start, Submit for review (a note or a file is required), Accept or Send back with a comment (reviewers), or Not applicable with a reason. Give each control an owner and a due date; owners, reviewers and @mentioned teammates are notified, and by email if they turned it on in Settings.
CSV export provides a flat systems-and-controls register. JSON export includes nested evidence metadata and audit events.
The evidence pack is one ZIP for auditors: the register, every control, the full audit log and the current evidence files, with a manifest.json of SHA-256 hashes. Each file is re-checked against the hash recorded at upload; a file that no longer matches is listed as failed instead of exported. Download it for the whole workspace or for one system.
Bulk-add an existing inventory from CSV (columns name, purpose, department, business_owner, provider, lifecycle, markets, data_class, impact_scope, customer_facing, autonomous_actions) or JSON, including a HowAISafe JSON export. Every row is checked first; nothing is written until the whole file is valid and fits the plan. Names already registered are skipped.
Read tokens (systems:read) expose GET /api/safe/v1/systems. Tokens with write access (systems:write) can also POST /api/safe/v1/systems with the import fields as JSON, and PATCH /api/safe/v1/tasks/{id} with any of status (missing, in_progress, ready_for_review, not_applicable), evidenceNote, assignee, dueDate and revision. A stale revision returns 409. Tokens can never accept evidence; acceptance stays with a human reviewer. Every API change is attributed to the token in the audit log. Secrets are shown once and stored only as SHA-256 hashes.
Owners and admins can add up to five HTTPS endpoints. Every audit event is POSTed as JSON (id, type, createdAt, systemId, data) within about a minute, with headers X-HowAISafe-Event, X-HowAISafe-Delivery and X-HowAISafe-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + body with your signing secret. Reject old timestamps, compare signatures in constant time and de-duplicate on id. Non-2xx responses are retried after 1, 5, 30, 120 and 720 minutes; an endpoint that keeps failing is paused until you send a test.
Accepted controls return to review after the workspace recertification cycle (365 days by default). Replaced evidence versions, and evidence on systems retired longer than the retention period, are purged; file hashes stay in the audit log. When the ruleset version changes, systems in use are re-triaged and gain any new controls. Owners get a weekly reminder about overdue and upcoming controls.
curl -sS https://safe.howaicite.com/api/safe/v1/systems \
-H "Authorization: Bearer $HOWAISAFE_API_TOKEN"
# with a write token
curl -sS -X PATCH https://safe.howaicite.com/api/safe/v1/tasks/$TASK_ID \
-H "Authorization: Bearer $HOWAISAFE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"ready_for_review","evidenceNote":"Policy v3 in GRC"}'Keep tokens in a secret manager. Never place them in client-side code, source control or support messages.