> 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/api/zh/toss-login.md).

# Toss 登录

## 获取 AccessToken

> 这是一个根据 Authorization Code 颁发 Access Token 和 Refresh Token 的 API。颁发的 Access Token 有效期为 1 小时。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明               |\
> \| --------- | ---------------- |\
> \| \`4050\`       | 不是注册到认证服务器的迷你应用。 |\
> \| \`4095\`       | 请求已超出限制。请稍后再试。   |\
> \
> 此 API 可以原样传递所对接内部系统的错误代码。未文档化的 \`errorCode\` 会按失败处理，请参考 \`reason\` 消息。\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是一个处理基于 OAuth2 的应用连接和用户认证的 API。","name":"toss-login"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"GenerateTokenRequest":{"description":"这是用于发放 OAuth2 token 的请求正文。","properties":{"authorizationCode":{"description":"这是通过 OAuth2 认证流程发放的 Authorization Code。此代码会在用户完成认证后作为查询参数传递到重定向 URL。","type":"string"},"referrer":{"description":"这是用户进入应用的来源路径。例如，表示通过深度链接、推送通知、应用内横幅等哪种路径使用了该功能。","type":"string"}},"required":["authorizationCode","referrer"],"type":"object"},"TossApiSuccessGenerateTokenResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/GenerateTokenResponse"}},"required":["resultType","success"],"type":"object"},"GenerateTokenResponse":{"description":"这是 OAuth2 token 发放请求的响应信息。","properties":{"accessToken":{"description":"这是在 API 调用成功时发放的访问令牌。该令牌在需要用户认证的 API 请求中作为 Authorization 头使用。","type":"string"},"expiresIn":{"description":"这是访问令牌的有效期（秒）。超过此时间后，需要使用刷新令牌重新发放新令牌。","format":"int64","type":"integer"},"refreshToken":{"description":"这是访问令牌过期后用于重新发放的刷新令牌。可以使用该令牌请求新的访问令牌。","type":"string"},"scope":{"description":"表示可以使用该令牌执行的操作范围。例如，可能包含查询用户资料或发送消息的权限。","type":"string"},"tokenType":{"description":"表示令牌的类型。通常固定为 'Bearer'。","type":"string"}},"required":["accessToken","expiresIn","refreshToken","scope","tokenType"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/user/oauth2/generate-token":{"post":{"description":"这是一个根据 Authorization Code 颁发 Access Token 和 Refresh Token 的 API。颁发的 Access Token 有效期为 1 小时。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明               |\n| --------- | ---------------- |\n| `4050`       | 不是注册到认证服务器的迷你应用。 |\n| `4095`       | 请求已超出限制。请稍后再试。   |\n\n此 API 可以原样传递所对接内部系统的错误代码。未文档化的 `errorCode` 会按失败处理，请参考 `reason` 消息。\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"generateOauth2Token","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTokenRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessGenerateTokenResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessGenerateTokenResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"请求成功，返回已颁发的令牌信息。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"获取 AccessToken","tags":["toss-login"]}}}}
```

## 获取用户信息

> 这是一个使用 Access Token 查询已登录用户信息的 API。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明             |\
> \| --------- | -------------- |\
> \| \`4010\`       | 找不到认证信息。       |\
> \| \`4095\`       | 请求已超出限制。请稍后再试。 |\
> \
> 此 API 可以原样传递所对接内部系统的错误代码。未文档化的 \`errorCode\` 会按失败处理，请参考 \`reason\` 消息。\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是一个处理基于 OAuth2 的应用连接和用户认证的 API。","name":"toss-login"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"TossApiSuccessLoginMeResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/LoginMeResponse"}},"required":["resultType","success"],"type":"object"},"LoginMeResponse":{"description":"OAuth2 登录用户信息响应","properties":{"agreedTerms":{"description":"这是用户同意的条款 ID 列表。","items":{"type":"string"},"type":"array"},"birthday":{"description":"这是出生日期。为 YYYYMMDD 格式的 8 位字符串。","type":"string"},"callingCode":{"description":"这是国家电话代码。例如，韩国是 '82'。","type":"string"},"ci":{"description":"这是 CI（关联信息）值。进行本人认证时发放。","type":"string"},"di":{"description":"这是 DI（重复注册确认信息）值。用于确认是否为同一用户。","type":"string"},"email":{"description":"这是邮箱地址。如果未同意提供，则为 null。","type":"string"},"gender":{"description":"这是性别信息。是 'M'（男性）或 'F'（女性）其中之一。","type":"string"},"name":{"description":"这是用户姓名。如果未同意提供姓名，则为 null。","type":"string"},"nationality":{"description":"这是国籍代码。例如，韩国是 'KR'。","type":"string"},"phone":{"description":"这是电话号码。不含国家代码，只包含数字。","type":"string"},"scope":{"description":"这是包含在令牌中的权限范围。多个 scope 以空格分隔。","type":"string"},"userKey":{"description":"这是用户的唯一标识符。","format":"int64","type":"integer"}},"required":["agreedTerms","userKey"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/user/oauth2/login-me":{"get":{"description":"这是一个使用 Access Token 查询已登录用户信息的 API。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明             |\n| --------- | -------------- |\n| `4010`       | 找不到认证信息。       |\n| `4095`       | 请求已超出限制。请稍后再试。 |\n\n此 API 可以原样传递所对接内部系统的错误代码。未文档化的 `errorCode` 会按失败处理，请参考 `reason` 消息。\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"loginMe","parameters":[{"description":"这是包含 Bearer 形式 Access Token 的 Authorization 头值。Access Token 通过 [获取 AccessToken](https://developers-apps-in-toss.toss.im/api/zh/toss-login#post-api-partner-v1-apps-in-toss-user-oauth2-generate-token) API 颁发。","in":"header","name":"Authorization","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessLoginMeResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessLoginMeResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"请求成功，查询到的用户个人资料信息会作为响应返回。部分项目可能会根据用户同意情况而为 `null`。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"没有 `Authorization` 头。`error.data` 是空对象，`error.reason` 会以 `Unknown Error` 返回。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"获取用户信息","tags":["toss-login"]}}}}
```

## 重新获取 AccessToken

> 这是一个使用 Refresh Token 重新颁发 Access Token 的 API。Refresh Token 的有效期为 14 天。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明               |\
> \| --------- | ---------------- |\
> \| \`4050\`       | 不是注册到认证服务器的迷你应用。 |\
> \| \`4095\`       | 请求已超出限制。请稍后再试。   |\
> \
> 此 API 可以原样传递所对接内部系统的错误代码。未文档化的 \`errorCode\` 会按失败处理，请参考 \`reason\` 消息。\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是一个处理基于 OAuth2 的应用连接和用户认证的 API。","name":"toss-login"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"RefreshTokenRequest":{"description":"这是使用已签发的 refresh token 重新签发 access token 的请求。","properties":{"refreshToken":{"description":"这是已签发的 refresh token。可使用该 token 请求新的 access token。","type":"string"}},"required":["refreshToken"],"type":"object"},"TossApiSuccessRefreshTokenResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/RefreshTokenResponse"}},"required":["resultType","success"],"type":"object"},"RefreshTokenResponse":{"description":"OAuth2 令牌刷新响应","properties":{"accessToken":{"description":"这是新签发的 access token。","type":"string"},"expiresIn":{"description":"这是 access token 的有效期（秒）。","format":"int64","type":"integer"},"refreshToken":{"description":"这是新签发的 refresh token。","type":"string"},"scope":{"description":"这是 access token 的权限范围（scope）。例如：查看用户资料、发送消息等","type":"string"},"tokenType":{"description":"这是令牌类型。通常固定为 'Bearer'。","type":"string"}},"required":["accessToken","expiresIn","refreshToken","scope","tokenType"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/user/oauth2/refresh-token":{"post":{"description":"这是一个使用 Refresh Token 重新颁发 Access Token 的 API。Refresh Token 的有效期为 14 天。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明               |\n| --------- | ---------------- |\n| `4050`       | 不是注册到认证服务器的迷你应用。 |\n| `4095`       | 请求已超出限制。请稍后再试。   |\n\n此 API 可以原样传递所对接内部系统的错误代码。未文档化的 `errorCode` 会按失败处理，请参考 `reason` 消息。\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"refreshOauth2Token","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessRefreshTokenResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessRefreshTokenResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"请求成功，返回重新颁发的 Access Token 相关信息。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"重新获取 AccessToken","tags":["toss-login"]}}}}
```

## 使用 AccessToken 解除登录连接

> 这是一个使用 Authorization 头中的 Access Token 解除该用户连接的 API。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明               |\
> \| --------- | ---------------- |\
> \| \`4050\`       | 不是注册到认证服务器的迷你应用。 |\
> \| \`4010\`       | 找不到认证信息。         |\
> \| \`4095\`       | 请求已超出限制。请稍后再试。   |\
> \
> 此 API 可以原样传递所对接内部系统的错误代码。未文档化的 \`errorCode\` 会按失败处理，请参考 \`reason\` 消息。\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是一个处理基于 OAuth2 的应用连接和用户认证的 API。","name":"toss-login"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"TossApiSuccessDisconnectUserByAccessTokenResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/DisconnectUserByAccessTokenResponse"}},"required":["resultType","success"],"type":"object"},"DisconnectUserByAccessTokenResponse":{"description":"使用用户的 OAuth2 Access Token 解除该用户的连接。通常在用户希望自行断开连接时使用此 API。","properties":{"userKey":{"description":"这是已解除连接用户的唯一 userKey 值。该值用于在内部系统中识别用户。","format":"int64","type":"integer"}},"required":["userKey"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token":{"post":{"description":"这是一个使用 Authorization 头中的 Access Token 解除该用户连接的 API。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明               |\n| --------- | ---------------- |\n| `4050`       | 不是注册到认证服务器的迷你应用。 |\n| `4010`       | 找不到认证信息。         |\n| `4095`       | 请求已超出限制。请稍后再试。   |\n\n此 API 可以原样传递所对接内部系统的错误代码。未文档化的 `errorCode` 会按失败处理，请参考 `reason` 消息。\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"removeByAccessToken","parameters":[{"description":"这是包含用户 Access Token 的 Authorization 头值。Access Token 通过 [获取 AccessToken](https://developers-apps-in-toss.toss.im/api/zh/toss-login#post-api-partner-v1-apps-in-toss-user-oauth2-generate-token) API 颁发。","in":"header","name":"Authorization","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessDisconnectUserByAccessTokenResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessDisconnectUserByAccessTokenResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"请求成功，已成功解除与 Access Token 对应用户的连接。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"没有 `Authorization` 头。`error.data` 是空对象，`error.reason` 会以 `Unknown Error` 返回。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"使用 AccessToken 解除登录连接","tags":["toss-login"]}}}}
```

## 用 userKey 断开登录连接

> 这是一个使用 userKey 解除该用户登录连接的 API。响应中仅包含已解除连接的用户的 \`userKey\`。\
> \
> \### 业务错误代码\
> \
> 下面的错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明               |\
> \| --------- | ---------------- |\
> \| \`4050\`       | 不是注册到认证服务器的迷你应用。 |\
> \| \`4095\`       | 请求已超出限制。请稍后再试。   |\
> \
> 此 API 可以原样传递所对接内部系统的错误代码。未文档化的 \`errorCode\` 会按失败处理，请参考 \`reason\` 消息。\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是一个处理基于 OAuth2 的应用连接和用户认证的 API。","name":"toss-login"}],"servers":[{"description":"运维（快捷登录·消息发送·Toss 积分发放等）","url":"https://apps-in-toss-api.toss.im"}],"security":[{"mutualTLS":[]}],"components":{"securitySchemes":{"mutualTLS":{"description":"这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考 [使用服务器 API](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"DisconnectUserByUserKeyRequest":{"description":"通过 UserKey 解除 OAuth2 用户连接请求","properties":{"userKey":{"description":"这是要解除连接的用户唯一标识符。用于在内部系统中识别用户。","format":"int64","type":"integer"}},"required":["userKey"],"type":"object"},"TossApiSuccessDisconnectUserByUserKeyResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/DisconnectUserByUserKeyResponse"}},"required":["resultType","success"],"type":"object"},"DisconnectUserByUserKeyResponse":{"description":"通过 UserKey 解除 OAuth2 用户连接响应","properties":{"userKey":{"description":"这是已解除连接用户的唯一标识符。与请求中使用的值相同。","format":"int64","type":"integer"}},"required":["userKey"]},"TossApiFail":{"description":"这是失败响应信封。业务错误会以 HTTP 200 返回，因此请务必确认 `resultType`。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiValidationFail":{"description":"这是请求字段验证失败时的响应。","properties":{"error":{"$ref":"#/components/schemas/TossApiValidationFailError"},"resultType":{"description":"这是处理结果。除 `SUCCESS` 之外的值都应视为失败处理。通常为 `FAIL`。","enum":["FAIL","HTTP_TIMEOUT","NETWORK_ERROR","EXECUTION_FAIL","INTERRUPTED","INTERNAL_ERROR"],"type":"string"},"success":{"description":"失败时始终为 null。"}},"required":["error","resultType"],"type":"object"},"TossApiValidationFailError":{"description":"这是错误详细信息。","properties":{"data":{"description":"这是错误附加信息。请求超过限额时会包含 `retryAfterSeconds`。","properties":{"errorDetails":{"description":"这是按字段列出的验证失败详情列表。","items":{"$ref":"#/components/schemas/TossApiFieldError"},"type":"array"}},"type":"object"},"errorCode":{"description":"这是错误代码。请参阅各 API 的业务错误代码表。","type":"string"},"errorType":{"description":"这是内部错误分类值。请在错误区分中使用 `errorCode`。","format":"int32","type":"integer"},"reason":{"description":"这是可读的人类错误说明。","type":"string"},"title":{"description":"这是错误标题。大多数情况下为 null。","type":"string"}},"required":["errorCode","reason"],"type":"object"},"TossApiFieldError":{"description":"这是按字段列出的验证失败详情列表。","properties":{"field":{"description":"这是验证失败的字段名。","type":"string"},"message":{"description":"这是验证失败原因。","type":"string"},"rejectedValue":{"description":"这是被拒绝的输入值。"}},"type":"object"}}},"paths":{"/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key":{"post":{"description":"这是一个使用 userKey 解除该用户登录连接的 API。响应中仅包含已解除连接的用户的 `userKey`。\n\n### 业务错误代码\n\n下面的错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明               |\n| --------- | ---------------- |\n| `4050`       | 不是注册到认证服务器的迷你应用。 |\n| `4095`       | 请求已超出限制。请稍后再试。   |\n\n此 API 可以原样传递所对接内部系统的错误代码。未文档化的 `errorCode` 会按失败处理，请参考 `reason` 消息。\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"removeByUserKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectUserByUserKeyRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessDisconnectUserByUserKeyResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessDisconnectUserByUserKeyResponse"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"请求成功，基于 `userKey` 已解除连接的用户的 `userKey` 返回。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求正文不符合格式。请在`error.data.errorDetails`中查看各字段详情。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"用 userKey 断开登录连接","tags":["toss-login"]}}}}
```


---

# 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/api/zh/toss-login.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.