# XBOSS auth.md

You are an agent. XBOSS serves Korean government tax and social insurance data over REST and MCP.
You can open an account for your user with only their email address: you get a working key at once,
and you pass the returned claimUrl to your user. They enter the code sent to their mailbox to take
the account over. Never ask them to share that code with you. Follow the steps in order.

## Step 1 - Register

```http
POST https://api.xdata.kr/v1/public/agent-signup
Content-Type: application/json
User-Agent: <your agent name>
X-Env-Scope: production

{"email": "<your user's email address>"}
```

Send only the email address of the person who will own the account. Ask them for it, and tell them
a mail from XBOSS will arrive. Your User-Agent becomes the key's name on their screen, so name yourself.

Optional public attribution: use an XBOSS tool manifest's `related_registered_workflow.signup_acquisition`
as the request's optional `acquisition` only when no prior approved attribution is known. If prior approved
attribution is known, preserve its `source`, `campaign` and `product_slug`; attach or update only the current
`tool_slug`. Never overwrite a known GitHub origin with the manifest's website default.
Approved source/campaign pairs: `github/xboss_connect`, `xboss-connect/xboss_connect`, `website/result_templates`, `website/free_tools`. Optional `tool_slug` labels: `vat`, `business-status`, `estimate`, `payslip`, `labor-cost`, `registration-ocr`, `business-info`, `premises-lookup`, `commercial-vehicle-history`.
A free-tools landing may omit `tool_slug`. `product_slug` is an actual published product label, independent
of the tool label. Never invent attribution from a URL or replace a product with a tool ID.
Do not put emails, visitor IDs, referrers, cookies or tokens inside acquisition. This metadata is optional
and does not prove identity. The request model in the public OpenAPI is the validation contract.

Send `X-Env-Scope: production` on this request and on Step 2 - without it the request is rejected.
On these two requests it does not decide what the new key can call (see Step 3).

**201 Created** - a new account in the demo stage (the free plan, named 라이트 on the site, comes later - see Step 3):

| Field | Meaning |
|---|---|
| `status` | `created` |
| `agentName` | the key name your user will see |
| `clientId` | your client_id |
| `handoffToken` | a one-time token for your client_secret (Step 2) |
| `handoffExchange` | `method`, `url`, `bodyField`, `expiresInSeconds` - where and how long to exchange it |
| `claimUrl` | the page where your user takes the account over (Step 4) |
| `claimExpiresAt` | until when `claimUrl` works |
| `emailNotification` | `status` (`accepted`, `failed`, `not_configured`), `deliveryConfirmed` (always false) |
| `terms` | a sentence for your user - relay it as it is |
| `next` | `stage` (`claim`), `who` (`user`), `say_to_user`, `action_url` - relay `say_to_user` as it is |

**200 OK** with `status` `existing_account` - that address already has an account. No key is issued and
nothing in that account changed. `emailNotification` separately reports submission status. Relay `next.say_to_user`: they sign in, create a
key at https://console.xdata.kr/keys (`next.action_url`) and give it to you.

**400** - fix the email address and send again. **429** - too many requests from you or to that
mailbox; wait and try later. **404** - agent sign-up is not open.

A 201 proves account creation, not email delivery. `accepted` means the SMTP submission returned,
not that the mailbox received it. On `failed` or `not_configured`, keep the returned claimUrl and
handoff token safely; give the claimUrl to the owner and let them use its existing resend control.
Resend reports `delivery_failed` if submission fails. Do not register again or issue another key.
If claimUrl was lost, ask the owner for permission to request an ownership link:
`POST https://api.xdata.kr/v1/public/agent-claim/recover-link` with JSON
`{"email":"<owner-provided email>"}`, `X-Env-Scope: production`, no Authorization.
The same `{"status":"accepted"}` response acknowledges the request regardless of account eligibility
or mail outcome. The private link is sent only to the owner mailbox. Never ask for their mailbox code.
This recovers ownership of the existing account, not a lost key's plaintext secret. It creates no
new account or key and extends no trial or original claim deadline. The owner still enters the OTP,
name, password and consent on the existing claim page. Recovery defaults to revoking the old agent key;
the normal agent-provided claim link keeps its original default. Do not repeat signup or institution jobs.

## Step 2 - Exchange the handoff token (once, within 300 seconds)

```http
POST https://api.xdata.kr/v1/auth/handoff/exchange
Content-Type: application/json
X-Env-Scope: production

{"handoff_token": "<handoffToken>"}
```

The response is `{"client_id": "...", "client_secret": "..."}`. The client_secret is shown only here:
keep it in your credential store, never in the chat. Request validation errors and HTTP 429
rate-limit rejections happen before exchange and do not consume the token. Correct the request
(including its environment), or wait as instructed, and retry within the token's lifetime.

An exchange-handler response with status 404, 409, 410 means the token is unknown,
already used or expired. The key is not lost, but you cannot read its secret again; after your user
takes the account over (Step 4) they can create a new key at https://console.xdata.kr/keys.

If the response is lost or a server error occurs, do not assume whether exchange succeeded. Retry
exchange while the token is valid; if it reports a token failure, use the recovery above. Do not
register another account to recover the secret.

## Step 3 - Call the API

```http
Authorization: Basic base64(client_id:client_secret)
```

- REST: `https://api.xdata.kr/v1/...` - reference at https://developer.xdata.kr
- MCP (Streamable HTTP): `POST https://api.xdata.kr/mcp` - read `initialize.instructions` first

Current demo offer (real_test), starting on demo approval: 21 days; shared per organization; 1000 usage tokens per day; 5000 usage tokens for the entire trial; 0 blocks usage. The trial total does not refill at a calendar-month boundary. 라이트: 0 KRW / MONTHLY; VAT included; daily tokens=100; monthly tokens=1000. PRO: 495000 KRW / MONTHLY; VAT included; daily tokens=80000; monthly tokens=80000. 스탠다드: 165000 KRW / MONTHLY; VAT included; daily tokens=20000; monthly tokens=20000. A null limit means no limit; 0 blocks usage. GET /v1/public/plans is authoritative. Account-specific remaining usage comes from GET /v1/membership/me.

Tools that read an institution need your user to register a credential in the
console first; the tool's answer tells you when and where.

Every REST request needs an environment: the `X-Env-Scope` header, the `env_scope` query parameter or a
path prefix such as `/v1/real_test/`; without one the request is rejected. MCP chooses it for you. A new
key can call `real_test`; `production` answers 403 `POLICY_ENV_FORBIDDEN` until your user starts the plan.

Read the live allowance with `GET https://api.xdata.kr/v1/membership/me` (send an environment; an API key or a console
token works, an MCP OAuth token is refused). A new key reads the demo allowance (`quota_after`,
`demo_ends_at`) on `real_test` only. `plan_name` reads 라이트 in the demo stage too: read the stage
from `membership_tier` (`FREE` = demo, `PAID` = plan started).

## Step 4 - Hand the account to your user

Relay `next.say_to_user` from Step 1; it carries `claimUrl`. Your user:

1. receives a mail with a 6-digit code (valid 24 hours, 5 tries; the claim page sends a new one),
2. opens `claimUrl` (valid 30 days, until `claimExpiresAt`) and enters the code there,
3. sets their name and password and agrees to the terms,
4. decides about your key: keep it, or revoke it.

The code belongs on the claim page only. Do not ask for it - you cannot complete this step for them.

## Key lifecycle

- The key works from Step 2 on, before and after the claim.
- It stops working when your user revokes it on the claim page, uses the "I did not request this" link
  in the mail (that also closes the account, and only works before the claim), or revokes it later in
  the console.
- When your calls start failing authentication, tell your user. Registering again with the same address
  answers `existing_account`. Do not register again or try to issue another key for an existing account;
  give the user the existing-account response and console link.
