> 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/user-key.md).

# 用户识别密钥

## 兑换匿名用户认证码

> 将迷你应用通过 SDK 获取的一次性认证码兑换为匿名用户识别密钥。该认证码发放后 5 分钟内只能使用一次，并且只能用发放该认证码的迷你应用的证书兑换。合作伙伴服务器可以使用此响应中的匿名用户识别密钥查询或创建会员。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明 |\
> \| --- | --- |\
> \| \`4011\` | 匿名用户认证码无效。 |\
> \| \`4095\` | 请求已超过限制。请稍后重试。 |\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是合作伙伴服务器用于验证用户识别密钥或兑换认证码的 API。","name":"user-key"}],"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":{"ExchangeAnonAuthCodeRequest":{"description":"这是将匿名用户认证码兑换为匿名用户识别密钥的请求正文。","properties":{"code":{"description":"这是迷你应用通过 SDK 获取并传递给合作伙伴服务器的一次性认证码。发放后 5 分钟内只能使用一次。","type":"string"}},"required":["code"]},"TossApiSuccessExchangeAnonAuthCodeResponse":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"$ref":"#/components/schemas/ExchangeAnonAuthCodeResponse"}},"required":["resultType","success"],"type":"object"},"ExchangeAnonAuthCodeResponse":{"description":"这是兑换匿名用户认证码的结果。","properties":{"anonKey":{"description":"这是获得该认证码的用户的匿名用户识别密钥。在同一个迷你应用中始终为相同的值。","type":"string"}},"required":["anonKey"]},"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/users/anon-key/exchange":{"post":{"description":"将迷你应用通过 SDK 获取的一次性认证码兑换为匿名用户识别密钥。该认证码发放后 5 分钟内只能使用一次，并且只能用发放该认证码的迷你应用的证书兑换。合作伙伴服务器可以使用此响应中的匿名用户识别密钥查询或创建会员。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --- | --- |\n| `4011` | 匿名用户认证码无效。 |\n| `4095` | 请求已超过限制。请稍后重试。 |\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"exchangeAnonAuthCode","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeAnonAuthCodeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessExchangeAnonAuthCodeResponse"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessExchangeAnonAuthCodeResponse"},{"$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":"兑换匿名用户认证码","tags":["user-key"]}}}}
```

## 验证匿名用户识别密钥

> 检查通过 x-anon-key 头传递的匿名用户识别密钥是否为已发放的密钥，以及是否属于调用方迷你应用。这并不能证明发起请求的一方就是该用户。用户登录（sign-in）请使用匿名用户认证码兑换 API。\
> \
> \### 业务错误代码\
> \
> 以下错误会以 HTTP 200 和 \`resultType: FAIL\` 响应。\
> \
> \| errorCode | 说明 |\
> \| --- | --- |\
> \| \`4010\` | 找不到认证信息。 |\
> \| \`4095\` | 请求已超过限制。请稍后重试。 |\
> \
> \*\*请求限额\*\*: 每个应用每分钟 3,000 次

```json
{"openapi":"3.1.0","info":{"title":"Apps in Toss 合作伙伴 API","version":"1.0.0"},"tags":[{"description":"这是合作伙伴服务器用于验证用户识别密钥或兑换认证码的 API。","name":"user-key"}],"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":{"TossApiSuccessBoolean":{"description":"这是成功响应信封。","properties":{"resultType":{"description":"这是处理结果。成功时为 `SUCCESS`。","enum":["SUCCESS"],"type":"string"},"success":{"description":"这是成功时的实际响应数据。","type":"boolean"}},"required":["resultType","success"],"type":"object"},"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/users/anon-key/verify":{"post":{"description":"检查通过 x-anon-key 头传递的匿名用户识别密钥是否为已发放的密钥，以及是否属于调用方迷你应用。这并不能证明发起请求的一方就是该用户。用户登录（sign-in）请使用匿名用户认证码兑换 API。\n\n### 业务错误代码\n\n以下错误会以 HTTP 200 和 `resultType: FAIL` 响应。\n\n| errorCode | 说明 |\n| --- | --- |\n| `4010` | 找不到认证信息。 |\n| `4095` | 请求已超过限制。请稍后重试。 |\n\n**请求限额**: 每个应用每分钟 3,000 次","operationId":"verifyAnonKey","parameters":[{"description":"用于验证用户的密钥。可通过迷你应用 SDK 的 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/sdk/domains-api/user/user.getanonymouskey) 函数获取","in":"header","name":"x-anon-key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"discriminator":{"mapping":{"FAIL":"#/components/schemas/TossApiFail","SUCCESS":"#/components/schemas/TossApiSuccessBoolean"},"propertyName":"resultType"},"oneOf":[{"$ref":"#/components/schemas/TossApiSuccessBoolean"},{"$ref":"#/components/schemas/TossApiFail"}]}}},"description":"匿名用户识别密钥验证结果会返回 true 或 false。"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiValidationFail"}}},"description":"请求格式不正确。`error.data` 是空对象，`error.reason` 会返回为 `Unknown Error`。缺少 `x-anon-key` 头不会返回此响应，而是作为 HTTP 200 的业务错误（`4010`）返回。"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TossApiFail"}}},"description":"未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。"}},"summary":"验证匿名用户识别密钥","tags":["user-key"]}}}}
```


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://developers-apps-in-toss.toss.im/api/zh/user-key.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

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.