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

## 获取 Access Token

> 这是通过 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/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 调用成功时发放的 access token。用户认证所需的 API 请求会将该 token 放入 Authorization 头中使用。","type":"string"},"expiresIn":{"description":"这是 access token 的有效时间（秒）。超过该值后需要使用 refresh token 重新获取新 token。","format":"int64","type":"integer"},"refreshToken":{"description":"这是在 access token 过期后用于重新发放的 refresh token。可以用该 token 请求新的 access token。","type":"string"},"scope":{"description":"表示 token 可执行操作的范围。例如，可能包含查询用户资料或发送消息的权限。","type":"string"},"tokenType":{"description":"表示 token 的类型。通常固定为 'Bearer'。","type":"string"}},"required":["accessToken","expiresIn","refreshToken","scope","tokenType"]},"TossApiFail":{"description":"这是失败响应封装。业务错误会以 HTTP 200 返回，所以 `resultType`请务必确认。","properties":{"error":{"$ref":"#/components/schemas/TossApiError"},"resultType":{"description":"这是处理结果。 `SUCCESS`除 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`除 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":"获取 Access Token","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/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`除 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`除 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 是 [获取 Access Token](https://developers-apps-in-toss.toss.im/documentation/api/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`可能为 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"]}}}}
```

## 重新获取 Access Token

> 这是使用 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/integration/server-api) 文档。","type":"mutualTLS"}},"schemas":{"RefreshTokenRequest":{"description":"这是使用已发放的 refresh token 重新获取 access token 的请求。","properties":{"refreshToken":{"description":"这是已发放的 refresh 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`除 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`除 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":"重新获取 Access Token","tags":["toss-login"]}}}}
```

## 使用 Access Token 解除登录连接

> 这是使用 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/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`除 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`除 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 是 [获取 Access Token](https://developers-apps-in-toss.toss.im/documentation/api/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":"使用 Access Token 解除登录连接","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/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`除 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`除 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.