> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/guide/zh/authentication/intro.md).

# Toss 登录

在 Apps in Toss 中一次性接入 Toss 会员吧。只需一次同意，就能连贯完成注册、登录到信息提供，轻松实现 Toss 会员接入。

### Toss 登录的优点

* 无需单独的注册表单即可直接完成注册和登录，能够打造流畅的注册体验。
* 可以利用由 Toss 直接提供的高可信度用户信息。
* 再次访问时可以使用自动登录或一键登录。
* 即使重新安装 App 或更换设备，也能匹配为同一用户，从而减轻客服咨询处理负担。

{% hint style="info" %}
**请务必确认**

* 在迷你应用中，登录功能只能使用 Toss 登录。不能使用自有登录或其他便捷登录方式。
* 要使用功能性推送与通知、促销、Toss Pay，必须接入 Toss 登录。
  {% endhint %}

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FLvK8oLVnZMo83WkfM4X2%2Fimage.png?alt=media&#x26;token=d25c4cad-d817-4992-8eaa-95b26aa11059" alt=""><figcaption></figcaption></figure>

***

### 在控制台中设置

#### 1. 同意条款

要使用 Toss 登录，首先需要同意条款。同意条款可以在 Apps in Toss 控制台中进行，而且只能由被指定为代表管理员的账号进行。

#### 2. 设置

要接入登录，必须先在控制台完成预先设置。系统会根据你输入的信息自动配置用户条款同意页面。

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2F7wKRUxTjtvQLTMMaZrKl%2F%E1%84%8B%E1%85%AF%E1%86%AB%E1%84%87%E1%85%A9%E1%86%AB%2084%20(1).png?alt=media&#x26;token=e6b95b66-7b03-4f99-9c40-60b6a94ae6bc" alt=""><figcaption></figcaption></figure>

**要接入的服务**

如果已有正在使用 Toss 登录的服务，这里会显示。现有服务的会员标识符(`userKey`)可设置为与 Apps in Toss 的 Toss 登录相同。选择列表中的服务名称后，所选服务的 `userKey` 值会同样映射。

但是， `userKey`是仅在该 App 内唯一的值。即使是同一用户，App 不同， `userKey`的值也可能不同。

**同意项**

请选中要通过 Toss 登录收集的 **用户权限（scope）**。如果选择姓名、邮箱、性别以外的项目，则 **断开连接回调信息**必须填写。

<table data-search="false"><thead><tr><th>项目</th><th>说明</th></tr></thead><tbody><tr><td>姓名（USER_NAME）</td><td>用户的姓名。</td></tr><tr><td>邮箱（USER_EMAIL）</td><td>用户的邮箱。（Toss 注册时这不是必填项，因此可能没有值，在这种情况下 <code>null</code>会被传递。）</td></tr><tr><td>性别（USER_GENDER）</td><td>用户的性别。</td></tr><tr><td>生日（USER_BIRTHDAY）</td><td>用户的出生年月日。</td></tr><tr><td>国籍（USER_NATIONALITY）</td><td>用户的国籍。</td></tr><tr><td>电话号码（USER_PHONE）</td><td>用户的电话号码。</td></tr><tr><td>CI（USER_CI）</td><td>用于识别用户的唯一 KEY 值。（Connection Information）</td></tr></tbody></table>

{% hint style="warning" %}
Toss 不一定会收集邮箱地址，因此可能存在没有邮箱值（null）的用户。

请处理好，即使没有该值，App 也能正常运行。
{% endhint %}

<details>

<summary>什么是 CI？</summary>

CI（Connection Information）是由实名认证机构发放的 **唯一识别值**。即使同一用户注册多个服务 **也能被识别为同一人的不可变值**。CI 在需要实名验证的服务中 **常用于防止重复注册或进行本人识别** 。

CI 在个人信息保护法下属于个人可识别信息（PII）。在存储或使用时必须 **加密**，并遵守 **最小收集原则**。

</details>

**条款/同意文**

要在 Apps in Toss 中运营服务，需要注册条款。 **Toss 登录必需条款**（服务条款、向第三方提供个人信息同意）会自动包含。 **合作方服务条款、个人信息收集·使用同意、营销信息接收同意（可选）** 等需要自行注册。请附上符合服务目的的 **准确条款链接**。

条款类型可以从系统提供的示例中选择，也可以手动输入。如果想按条款分别管理，建议手动输入。

如果要将通过 Toss 登录获得的个人信息存储或转移到海外云区域或海外运营商的服务器上， **个人信息跨境转移同意书**请务必注册。该同意书中需包含接收方、接收国家、接收方联系方式、转移项目、转移时间和方式、使用目的、保存·使用期限。

<figure><img src="https://1415110023-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2Fs5JiMXMSTiQpALYwUzsF%2Fimage.png?alt=media&amp;token=0152c68e-0655-419f-af6e-00b18c2d929f" alt=""><figcaption></figcaption></figure>

请确认所有条款链接都能正确跳转，并且在页面上清晰可见。

{% hint style="warning" %}
**请注意**

该区域是 **必须满足法律要求的部分**。由于会根据服务性质而有所不同， **建议确认最新法律法规和指南，并接受法律咨询**。
{% endhint %}

<details>

<summary>可登记的条款项目</summary>

* **服务使用条款** — 权利·义务、责任范围、中止·终止、争议解决、条款变更通知、（如为付费则）支付·退款规定
* **个人信息收集·使用同意** — 收集项目、使用目的、保存·使用期限、拒绝同意时的不利影响
* **营销信息接收同意（可选）** — 收集项目、使用目的、保存期限、拒绝时的不利影响、电子传输媒介广告接收同意
* **夜间权益接收同意（可选）** — 明确是否在夜间（21:00\~08:00）发送
* **个人信息跨境转移同意（如适用）** — 如果将个人信息转移到境外，请明确接收方、接收国家、接收方联系方式、转移时间和方式、转移项目、使用目的、保存·使用期限

</details>

**断开连接回调信息**

当用户在 Toss App 中解除登录连接时，你可以通过已注册的回调 URL 接收事件。

当用户解除连接时，Toss 会 **删除全部同意条款和登录信息**。服务端也请务必进行会话或令牌清理等后续处理。

另外，当用户在 Toss App 中解除登录连接时，服务端也建议 **自动登出处理**或 **重新登录请求提示**。例如，显示“由于 Toss 连接已解除，需要重新登录”之类的文案会比较好。

| 项目            | 说明                                     |
| ------------- | -------------------------------------- |
| 回调 URL        | 这是用户解除登录连接时要调用的 URL。                   |
| HTTP 方法       | `GET` 或 `POST` 请选择其中之一。                |
| Basic Auth 标头 | 调用时会进行 base64 编码。请在解码后验证是否与控制台中输入的值一致。 |

**断开连接事件路径**

用户在 Toss App 中解除登录连接的路径共有 **3种**。在回调请求中可通过 `referrer` 值进行区分。

| referrer           | 说明                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `UNLINK`           | 当用户 **在 App 中直接断开连接时** 会调用。 在迷你应用中收到该事件后， **请执行登出处理**。（路径：Toss App > 设置 > 认证与安全 > 通过 Toss 登录的服务 > '断开连接'） |
| `WITHDRAWAL_TERMS` | 当用户 **当撤回登录服务条款时** 会调用。（路径：Toss App > 设置 > 法律信息及其他 > 条款及个人信息处理同意 > 各服务同意内容："Toss 登录" > '撤回同意'）            |
| `WITHDRAWAL_TOSS`  | 当用户 **当退出 Toss 会员时** 会调用。                                                                                 |

***

### 通过电子邮件领取解密密钥

完成 Toss 登录信息注册后，可以查看解密密钥。该密钥用于解密 Toss 登录响应数据。请点击“通过电子邮件领取解密密钥”按钮，安全地获取。

{% hint style="warning" %}
**解密密钥是敏感的安全信息。**

* 绝对不要对外泄露。
* 请保存在安全的内部密钥存储（如 Secret Manager 等）中。
* 如果需要重新发放，请通过 Channel Talk 咨询。
  {% endhint %}

<figure><img src="https://3177177630-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8pQgXiR5QAzduV54W8Om%2Fuploads%2FRLbRu8k6r3e7sKyJyRpv%2F%E1%84%80%E1%85%A9%E1%86%BC%E1%84%8C%E1%85%B5%E1%84%89%E1%85%A1%E1%84%92%E1%85%A1%E1%86%BC%2010.png?alt=media&#x26;token=de4bead1-da2b-4f05-a594-bcf3c901e24b" alt=""><figcaption></figcaption></figure>

***

### 进行开发对接

授权码发放（SDK）、AccessToken 发放、用户信息查询等 [接入方式](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#undefined)可查看。

***

### 在自有网页·App 中接入 Toss 登录

如果要在自有网页·App 中应用 Toss 登录，原本需要与 Toss 认证部门另签合同。不过，如果是在 Apps in Toss 中使用 Toss 登录的合作方，则无需单独合同也可以使用。

#### 1. 在 Apps in Toss 控制台申请 Toss 登录

请先确认上述指南，然后在 Apps in Toss 控制台申请 Toss 登录。

#### 2. 填写所需信息并申请发放 Client ID

请填写以下所有项目，并发送邮件至 Toss 认证部门(<cert.support@toss.im>)。

<table data-search="false"><thead><tr><th>项目</th><th>说明</th><th>示例</th></tr></thead><tbody><tr><td>网页/App 与否</td><td>请填写你要应用的服务形态（网页、App，或两者）</td><td>网页、App</td></tr><tr><td>会员识别键</td><td>请填写用于用户识别的键值</td><td>CI、邮箱</td></tr><tr><td>所需的个人信息项目</td><td>请填写希望获取的个人信息项目（可参考 Apps in Toss 控制台 > Toss 登录 > 同意项）</td><td>姓名、邮箱地址</td></tr><tr><td>条款列表</td><td>请填写要使用的条款标题、URL、是否必填</td><td>服务条款（必填） - https://example.com/terms</td></tr><tr><td>redirect_uri</td><td>请填写登录完成后要跳转的 URL</td><td>https://example.com/callback</td></tr><tr><td>计划接入的 App 版本</td><td>如果也要在合作方 App 中导入，请填写 App 版本</td><td>iOS 3.2.0，Android 2.8.1</td></tr><tr><td>是否使用登录断开连接 API</td><td>请填写是否使用该 API（未填写时会设为“未使用”）</td><td>未使用</td></tr><tr><td>网络信息</td><td>如果使用 VPN 或需要开发环境联调，则需要单独登记。请填写服务器的 IP 或 IP 段</td><td>123.45.67.89</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/guide/zh/authentication/intro.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.