> 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 登录

### Toss 登录的优点

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

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

* 在 Mini App 中，登录功能只能使用 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 登录，必须先同意条款。同意条款可在 App 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`）可以设置得与 App in Toss Toss 登录完全相同。在列表中选择服务名称后，所选服务的 `userKey` 值会以相同方式映射。

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

**同意项**

通过 Toss 登录收集的 **用户权限（scope）**&#x8BF7;进行选择。若选择姓名、邮箱、性别以外的项目，则 **断开连接回调信息**必须填写。

<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>会以 null 传递。）</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）的用户。

请处理为即使没有值，应用也能正常运行。
{% endhint %}

<details>

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

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

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

</details>

**条款/同意文**

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

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

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

<figure><img src="/files/7bb7671b95f8cde561279e653fb58c21a4febe59" alt=""><figcaption></figcaption></figure>

请确认所有条款链接都正确连接，并且在页面上清晰显示。

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

此部分是 **需要满足法律要求的部分**。根据服务性质内容可能不同， **建议确认最新法规和指南，并接受法律咨询**。
{% endhint %}

<details>

<summary>可注册的条款项目</summary>

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

</details>

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

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

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

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

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

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

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

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

***

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

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

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

* 绝对不要对外泄露。
* 请保存在安全的内部秘密存储库（如 Secret Manager）中。
* 如果需要重新发放，请通过 ChannelTalk 咨询。
  {% 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)可以查看。

***

### 将 Toss 登录接入自有 Web·App

要在自有 Web·App 中应用 Toss 登录，原本需要与 Toss 认证部门另行签约。不过，如果是已在 App in Toss 中使用 Toss 登录的合作方，则无需另行签约也可使用。

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

确认以上指南后，请先在 App 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>是否为 Web/App</td><td>请填写要应用的服务形态（Web、App 或两者）</td><td>Web、App</td></tr><tr><td>会员识别键</td><td>请填写用于用户识别的键</td><td>CI、邮箱</td></tr><tr><td>所需的个人信息项目</td><td>请填写想要获取的个人信息项目（请参考 App 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>预计接入的应用版本</td><td>如果也要在合作方应用中导入，请填写应用版本</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.