{ "status": "enabled", "service": "k-work-trust-agent-signup", "base_url": "https://k-work-trust-api.fly.dev", "generated_at": "2026-05-13T15:23:10.955Z", "mode": "provisional_key_or_email_verification_with_sha256_proof_of_work", "readiness_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/readiness", "whoami_endpoint": "https://k-work-trust-api.fly.dev/v1/auth/whoami", "proof_secret_configured": true, "proof_of_work": { "algorithm": "sha256", "digest_encoding": "hex", "input_template": "${nonce}:${subject}:${solution}", "difficulty_rule": "The hex digest must start with '0' repeated difficulty_hex_prefix_zeros times.", "solution_field": "proof.solution", "challenge_field": "proof.challenge", "max_solution_length": 160, "challenge_ttl_seconds": 300, "email_signup_difficulty_hex_prefix_zeros": 4, "provisional_signup_difficulty_hex_prefix_zeros": 4 }, "rate_limits": { "challenge_rate_limit_rpm": 12, "mutation_rate_limit_rpm": 4 }, "provisional": { "enabled": true, "trust_level": "provisional", "challenge_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/signup/provisional/challenge?agent_label=", "issue_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/signup/provisional", "default_quota": { "rate_limit_rpm": 1, "monthly_request_quota": 20 }, "official_sources": "disabled_by_default_until_email_verified_or_human_approved", "reject_existing_provisional_keys": false }, "email_verified": { "enabled": true, "trust_level": "email_verified", "challenge_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/signup/challenge?email=", "request_code_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/signup/request-code", "verify_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/signup/verify", "default_quota": { "rate_limit_rpm": 10, "monthly_request_quota": 200 } }, "key_policy": { "prefix": "kwt_", "plaintext_returned_once": true, "store_securely": true, "never_expose_publicly": true }, "abuse_guard": { "enabled": true, "behavior_based": true, "does_not_infer_nationality": true, "low_trust_max_records_per_request": 1, "low_trust_max_business_number_like_identifiers": 4, "blocks": [ "plaintext API keys or bearer tokens in request bodies", "personal identifier patterns such as resident registration or passport fields", "bulk or batch payloads from low-trust/provisional keys", "many distinct business-number-like identifiers from low-trust/provisional keys" ], "operator_controls": [ "KWT_ABUSE_GUARD_ENABLED=false disables the guard temporarily", "KWT_REJECT_PROVISIONAL_KEYS=true rejects existing provisional keys", "KWT_PROVISIONAL_ALLOW_OFFICIAL_SOURCES=false keeps provisional keys local-only" ] }, "failure_modes": [ { "code": "UNAUTHORIZED", "applies_to": [ "authenticated_api", "whoami" ], "http_status": 401, "category": "auth_failure", "retry": "do_not_retry_same_key", "agent_next_action": "Abort the protected call, verify the key with /v1/auth/whoami, and obtain a valid key through self-serve signup or the operator.", "escalation": "human_or_operator_if_the_agent_expected_this_key_to_be_active", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "RATE_LIMITED", "applies_to": [ "authenticated_api", "signup" ], "http_status": 429, "category": "temporary_limit", "retry": "retry_after_retry_after_seconds", "agent_next_action": "Wait for retry_after_seconds before retrying. If the workflow is urgent or repeated rate limits occur, escalate instead of looping.", "escalation": "human_review_or_alternative_route_for_time_sensitive_workflows", "safe_to_log": [ "request_id", "error.code", "retry_after_seconds" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "QUOTA_EXCEEDED", "applies_to": [ "authenticated_api" ], "http_status": 429, "category": "quota_exhausted", "retry": "do_not_retry_until_resets_at", "agent_next_action": "Stop automated calls for this key until resets_at or ask an operator for review. Do not request a manual key in public channels.", "escalation": "operator_review_required_for_quota_change", "safe_to_log": [ "request_id", "error.code", "quota.limit", "quota.used", "quota.resets_at" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "VALIDATION_BLOCKED", "applies_to": [ "workflow_response" ], "http_status": 200, "category": "business_rule_block", "retry": "retry_only_after_correcting_input", "agent_next_action": "Do not proceed with the workflow action. Preserve blocking_issues and evidence, then collect corrected fields or ask a human reviewer.", "escalation": "human_review_if_the_record_is_business_critical", "safe_to_log": [ "request_id", "status", "decision", "blocking_issues", "warnings" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "MANUAL_REVIEW", "applies_to": [ "workflow_response" ], "http_status": 200, "category": "needs_human_judgment", "retry": "do_not_auto_retry_without_new_information", "agent_next_action": "Route the normalized record, warnings, and evidence to a human reviewer before creating or updating downstream records.", "escalation": "human_review_required_before_downstream_write", "safe_to_log": [ "request_id", "status", "decision", "warnings", "evidence" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "SOURCE_UNAVAILABLE", "applies_to": [ "workflow_response", "official_sources" ], "http_status": 200, "category": "external_source_unavailable", "retry": "retry_later_or_continue_local_only_if_policy_allows", "agent_next_action": "Use local validation only when acceptable. If official-source evidence is required, pause the workflow and escalate with request_id and evidence.", "escalation": "human_or_operator_if_official_source_evidence_is_required", "safe_to_log": [ "request_id", "external_status", "warnings", "evidence" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "PROOF_OF_WORK_FAILED", "applies_to": [ "signup" ], "http_status": 403, "category": "signup_challenge_failure", "retry": "request_fresh_challenge_and_solve_contract", "agent_next_action": "Request a fresh challenge, solve sha256(nonce + ':' + subject + ':' + solution), and avoid repeated blind retries.", "escalation": "only_if_repeated_failures_indicate_onboarding_blocker", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "SIGNUP_RATE_LIMITED", "applies_to": [ "signup" ], "http_status": 429, "category": "signup_limit", "retry": "wait_before_requesting_another_challenge_or_mutation", "agent_next_action": "Wait before continuing signup. Do not ask for a pasted plaintext key; use the self-serve flow after the limit resets.", "escalation": "operator_review_only_for_repeated_legitimate_tester_blockers", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "ABUSE_GUARD_BLOCKED", "applies_to": [ "authenticated_api", "workflow_request" ], "http_status": 403, "category": "misuse_or_sensitive_input_guard", "retry": "do_not_retry_same_payload", "agent_next_action": "Stop the request. Remove secrets, sensitive personal identifiers, bulk records, or enumeration-like input before retrying with one synthetic or authorized business record.", "escalation": "operator_review_if_the_agent_believes_the_block_is_false_positive", "safe_to_log": [ "request_id", "error.code", "abuse.reason" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets", "personal_identifiers" ] } ] }