# 고객, 멤버십 및 권한

> One contact record per person, dynamic segments, passwordless customer sign-in and entitlements that decide who may access what.

> Markdown version of https://kanorio.com/ko/developers/products/customers. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/products/customers.md

Status: **Available**

폼을 작성하거나, 상품을 구매하거나, 로그인하는 모든 사람은 하나의 연락처(Contact)로 기록됩니다. Kanorio는 기능별로 별도의 목록을 유지하는 대신 모든 활동을 해당 기록에 통합합니다.

## 핵심 객체

- **연락처(Contacts):** 이름, 이메일, 전화번호, 동의 여부, 태그와 함께 해당 인물의 주문, 제출 내역, 코스 진행 상황을 포함합니다. 각 연락처에는 시스템 고유 ID(`externalId`, 사이트당 고유하며 한 번만 설정 가능)와 통합 필드를 위한 플랫한 `metadata`를 저장할 수 있으며, 로그인 상태(`accessStatus`)를 가집니다. 차단된 연락처는 로그인할 수 없지만, 주문 및 이메일 수신은 계속됩니다.
- **세그먼트(Segments):** 연락처에 대한 저장된 필터로, 예를 들어 '이번 달에 코스를 구매한 모든 사람'과 같이 자동으로 업데이트됩니다.
- **권한(Entitlements):** 코스나 회원 전용 기사와 같은 특정 콘텐츠에 대한 접근 권한을 부여합니다. 구매 시 자동으로 부여되며, 직접 부여하거나 취소할 수도 있습니다.
- **고객 세션(Customer sessions):** 고객은 일회용 코드를 사용하여 로그인하며 Customer API를 위한 `knr_cat_` 토큰을 발급받습니다.

멤버십, 구독, 크레딧 및 권한은 Kanorio에서 각각 별개의 개념입니다. 권한은 오직 '누가 무엇에 접근할 수 있는지'를 판단하는 용도로만 사용되며, 잔액이나 결제 플랜으로 사용되지 않습니다.

## API 활용 방법

- Management API를 사용하여 연락처, 세그먼트 및 권한을 관리합니다.
- Customer API를 사용하여 고객을 로그인시키고 자신의 데이터를 읽거나, `<kanorio-account>`(패스키, Google, 이메일 코드 등 사이트에서 활성화된 인증 방식 적용. `GET /site`의 `customerAccess.methods`에서 확인 가능)를 도입합니다.
- Content Delivery API의 게이트 콘텐츠는 고객의 토큰을 사용하여 반환할 데이터를 결정합니다.

- Webhooks는 연락처 변경(`customers.contact.created`, `updated`, `merged`, `access_changed`), 마케팅 동의 변경(`customers.consent.updated`) 및 권한 부여/취소 이벤트를 보고합니다. 연락처 페이로드에는 ID와 필드 이름만 포함되며 이메일 주소나 전화번호는 포함되지 않습니다. 값을 읽으려면 연락처를 조회(fetch)하십시오.

## What the APIs expose

| Capability | Status | API | Elements | Hosted site | Webhooks |
| --- | --- | --- | --- | --- | --- |
| Contacts & dynamic segments (external reference, metadata, sign-in status, manual merge) | Available | Management API `contacts.*` (`externalId`, `metadata`, look-up by `externalId`), `segments.*` | — | `/customers/contacts`, `/data/contacts`, `/data/segments` | `customers.contact.created`, `customers.contact.updated`, `customers.contact.merged`, `customers.contact.access_changed`, `customers.consent.updated`, `customers.form.submitted` |
| Customer login (magic link / 6-digit code) | Available | Customer `POST /auth/challenge`, `POST /auth/verify` → Bearer; `GET /me`; `DELETE /session` | `<kanorio-login>` (stores Bearer in localStorage, `kanorio:login` event) | `/account/login` | — |
| Entitlements (who may access what) | Available | Management API `entitlements.grant` / `revoke` / `list` / `check`; Customer `GET /access/:id` | `<kanorio-unit>` shows locked / preview / not-released states | Backoffice contact → Access tab; `/data/entitlements`; `/account/content` | `deliverables.entitlement.granted`, `deliverables.entitlement.revoked` |
| Membership tiers (ranked segments & automatic perks) | Planned | Planned (`tiers.*`) | — | Planned (`/data/tiers`) | — |

## API reference

- Management API: [Contacts](https://kanorio.com/en/developers/management-api/contacts) (5 operations)
- Management API: [Segments](https://kanorio.com/en/developers/management-api/segments) (1 operations)
- Management API: [Entitlements](https://kanorio.com/en/developers/management-api/entitlements) (4 operations)
- Customer API: [Openapi](https://kanorio.com/en/developers/customer-api/openapi) (1 operations)
- Customer API: [Auth](https://kanorio.com/en/developers/customer-api/auth) (6 operations)
- Customer API: [Passkeys](https://kanorio.com/en/developers/customer-api/passkeys) (4 operations)
- Customer API: [Me](https://kanorio.com/en/developers/customer-api/me) (1 operations)
- Customer API: [Session](https://kanorio.com/en/developers/customer-api/session) (1 operations)
- Customer API: [Access](https://kanorio.com/en/developers/customer-api/access) (1 operations)

## Webhook events

- `customers.sharedSender.softCap`: Fired once per day when sign-in code and similar emails sent from Kanorio's shared address exceed the site's daily soft cap; the bot check before sign-in is strengthened automatically. Nothing to do.
- `customers.sharedSender.paused`: Fired when those emails are paused for the site because of bounces, complaints or unusual volume; passkey, Google and signed-in customers are unaffected. Kanorio reviews and restores sending.
- `customers.sharedSender.resumed`: Fired when paused sign-in code emails resume after review.
- `customers.contact.created`: Fired when a contact is created from any source (checkout, form, import, manual, customer sign-up). Identities are listed by kind only; the data never includes the email address or phone number.
- `customers.contact.updated`: Fired when a contact's fields change (name, tags, note, locale, invoice preference, metadata, external reference, profile attributes). Lists the changed field names; fetch the contact to read the values.
- `customers.contact.merged`: Fired when two contacts become one, either automatically (the same person arrived with another identity) or by the owner. mergedContactId no longer exists; move your references to contactId.
- `customers.contact.access_changed`: Fired when the owner blocks or unblocks a customer's sign-in. BLOCKED revokes every session and refuses new sign-ins; orders, consent and emails are unaffected.
- `customers.consent.updated`: Fired when a contact's marketing consent on one channel changes (subscribed, pending confirmation, unsubscribed, bounced, complained).
- `deliverables.entitlement.granted`: Fired when a contact is granted access (Entitlement) to a deliverable or unit.
- `deliverables.entitlement.revoked`: Fired when a contact's Entitlement is revoked (e.g. refund or manual revocation).

Payloads: https://kanorio.com/en/developers/webhooks/events

## Elements

- `<kanorio-account>`: Customer sign-in panel: passkey, Google and a 6-digit email code, in the order the site enables them; signed-in customers see the account menu. Stores the customer token in localStorage and fires kanorio:login and kanorio:logout.
- `<kanorio-login>`: Deprecated alias of kanorio-account kept for pages that already embed it; same panel, same events.

## Recent changes

- 2026-11-03: Contacts: external references, metadata, sign-in status and contact webhooks
- 2026-10-31: Contacts: contacts.update replaces contacts.update_tags_note and can set the name
- 2026-10-27: entitlements.grant: bring-your-own payments (source EXTERNAL), idempotency keys

Full changelog: https://kanorio.com/en/developers/changelog

## For site owners

Dashboard help: https://kanorio.com/ko/help/customers