# K-Work Trust Agent Skill

K-Work Trust is an HTTPS API for AI agents that need to validate and normalize Korean business records before taking workflow actions.

## When To Use

Use this service before an agent creates, updates, imports, or enriches Korean vendor, customer, CRM, invoice, tax invoice, or ecommerce business records.

Best first endpoint:

```text
POST https://k-work-trust-api.fly.dev/v1/vendor-onboarding/validate
```

## Authentication

Send:

```text
Authorization: Bearer <kwt_api_key>
```

Before signup or first use, the agent can check deployment readiness:

```text
GET https://k-work-trust-api.fly.dev/v1/agent/readiness
```

If the agent does not have a key and cannot read email, use the provisional agent signup flow:

1. GET `https://k-work-trust-api.fly.dev/v1/agent/signup/provisional/challenge?agent_label=<agent-label>`
2. Solve the returned SHA-256 proof-of-work: compute `sha256(nonce + ":" + subject + ":" + solution)` until the hex digest starts with `"0".repeat(difficulty_hex_prefix_zeros)`.
3. POST `https://k-work-trust-api.fly.dev/v1/agent/signup/provisional` with agent_label, use_case, and proof.
4. Store the returned provisional `kwt_...` key securely. It is shown once.
5. Use the key with the very low provisional quota. Provisional keys use local validation only by default; official-source enrichment is available after email verification or explicit human approval.

To upgrade the same provisional key later:

1. POST `https://k-work-trust-api.fly.dev/v1/agent/signup/provisional/upgrade/request-code` with `Authorization: Bearer <kwt_api_key>` and an email.
2. Read the email verification code.
3. POST `https://k-work-trust-api.fly.dev/v1/agent/signup/provisional/upgrade/verify` with the same auth header, email, and code.

If the agent can read email from the start, use the email-verified agent signup flow:

1. GET `https://k-work-trust-api.fly.dev/v1/agent/signup/challenge?email=<email>`
2. Solve the returned SHA-256 proof-of-work using the returned nonce and normalized email subject.
3. POST `https://k-work-trust-api.fly.dev/v1/agent/signup/request-code` with email, agent_label, use_case, and proof.
4. Read the email verification code.
5. POST `https://k-work-trust-api.fly.dev/v1/agent/signup/verify` with email and code.
6. Store the returned `kwt_...` key securely. It is shown once.

After receiving a key, verify it without spending monthly quota:

```text
GET https://k-work-trust-api.fly.dev/v1/auth/whoami
Authorization: Bearer <kwt_api_key>
```

Use the response to check `trust_level`, `monthly_usage.remaining`, and whether official-source enrichment is allowed for this key.

## First Call

```http
POST https://k-work-trust-api.fly.dev/v1/vendor-onboarding/validate
Authorization: Bearer <kwt_api_key>
Content-Type: application/json

{
  "company_name": "Test Company",
  "registration_number": "1234567891",
  "phone_number": "01012345678"
}
```

Use `status`, `decision`, `blocking_issues`, `warnings`, `evidence`, and `agent_next_action` to decide whether to proceed, ask for review, or block the workflow.

## Money-Adjacent Gate

Before releasing a payment, invoice, settlement, purchase order, or similar workflow step, call:

```http
POST https://k-work-trust-api.fly.dev/v1/payment-or-invoice-release/validate
Authorization: Bearer <kwt_api_key>
Content-Type: application/json

{
  "company_name": "Test Company",
  "registration_number": "1234567891",
  "invoice_amount": 1500000,
  "currency": "KRW",
  "vendor_status": "approved",
  "vendor_last_verified_at": "2026-05-13T00:00:00Z",
  "payment_purpose": "software subscription"
}
```

If the response is `needs_review` or `blocked`, use `human_review_packet` and wait for approval before any money-adjacent action.

## Failure Modes and Escalation

Read `failure_modes` from the manifest, readiness endpoint, signup status, or OpenAPI before deciding how to recover. Treat it as the service's executable retry contract:

- `UNAUTHORIZED`: abort the protected call, verify the key with `/v1/auth/whoami`, and do not retry the same key blindly.
- `RATE_LIMITED`: wait for `retry_after_seconds`; escalate urgent or repeated limits instead of looping.
- `QUOTA_EXCEEDED`: stop automated calls until `resets_at` or ask an operator for quota review.
- `VALIDATION_BLOCKED`: do not proceed downstream until blocking issues are corrected.
- `MANUAL_REVIEW`: route warnings and evidence to a human reviewer before downstream writes.
- `SOURCE_UNAVAILABLE`: continue local-only only when policy allows; otherwise pause and escalate with `request_id`.
- `PROOF_OF_WORK_FAILED` or `SIGNUP_RATE_LIMITED`: request a fresh challenge or wait; never ask for a pasted plaintext key.

Use only `safe_to_log` fields in public logs or reports, and never log fields listed in `do_not_log`.

## Safety Policy

- Use only synthetic data, public test data, or records the agent is authorized to process.
- Do not treat the response as legal, tax, accounting, or official endorsement advice.
- Do not reveal the API key in public posts, logs, prompts, tool outputs, or error reports.
- If the API returns manual review or blocked, preserve evidence and ask a human before proceeding.

## Machine-Readable Metadata

- Manifest: https://k-work-trust-api.fly.dev/.well-known/k-work-trust-agent.json
- OpenAPI: https://k-work-trust-api.fly.dev/openapi.json
- Readiness: https://k-work-trust-api.fly.dev/v1/agent/readiness
- Key status: https://k-work-trust-api.fly.dev/v1/auth/whoami
- Tools: https://k-work-trust-api.fly.dev/v1/tools
- Remote MCP: https://k-work-trust-api.fly.dev/mcp