> 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/authentication/anonymous-key-auth-code.md).
# 사용자 식별키 인증 코드 발급
사용자 식별키 인증 코드를 발급하고 파트너 서버에서 교환해 사용자를 안전하게 확인하는 방법을 안내해요.
사용자 식별키 인증 코드는 미니앱에서 진입한 사용자를 파트너 서버에서 안전하게 확인할 수 있도록 돕는 기능이에요.
미니앱에서 사용자 식별키를 직접 파트너 서버로 전달하면, 식별키가 노출됐을 때 제3자가 같은 사용자처럼 요청할 수 있어요. 인증 코드를 사용하면 미니앱에서 짧게 유효한 코드를 발급하고, 파트너 서버가 이 코드를 앱인토스 서버에 교환해서 사용자 식별키를 받아요.
{% hint style="info" %}
**꼭 확인해 주세요**
* 사용자 식별키 인증 코드는 웹 미니앱에서 사용할 수 있어요.
* 토스 로그인과 별개의 기능이에요. 사용자 동의나 개인정보 제공 없이 미니앱 사용자를 식별할 때 사용해요.
* 인증 코드는 300초 동안 유효하고, 한 번만 사용할 수 있어요.
* 파트너 서버에서 코드를 교환하려면 앱인토스 파트너 API를 호출할 수 있는 mTLS 인증서가 필요해요.
{% endhint %}
***
### 언제 사용하나요
미니앱에서 파트너 서버로 전달되는 사용자 식별키의 위변조나 재사용을 막고, 실제 앱인토스에서 발급된 값인지 확인해야 할 때 사용할 수 있어요.
예를 들어 미니앱에서 사용자를 식별한 뒤 파트너 서버에서 자체 access token을 발급하거나, 파트너사 회원 DB에 앱인토스 사용자를 연결해야 하는 경우에 적합해요.
단순히 미니앱 내부에서 사용자별 데이터만 관리한다면 사용자 식별키 발급만으로 충분해요.
***
### 동작 방식
1. 미니앱이 SDK로 사용자 식별키 인증 코드를 발급해요.
2. 앱인토스 서버는 게이트웨이를 통해 확인한 미니앱과 사용자 정보를 기준으로 인증 코드를 만들어요. 클라이언트가 전달한 사용자 값은 신뢰하지 않아요.
3. 미니앱은 발급받은 인증 코드를 파트너 서버로 전달해요.
4. 파트너 서버는 mTLS로 앱인토스 파트너 API를 호출해 인증 코드를 교환해요.
5. 코드가 유효하면 파트너 서버는 사용자 식별키(`anonKey`)를 받아요.
이 흐름을 사용하면 파트너 서버가 받은 사용자 식별키가 실제 미니앱 사용자로부터 시작된 요청인지 확인할 수 있어요.
***
### 1. 미니앱에서 인증 코드 발급하기
웹 미니앱에서 `User.createAnonymousKeyAuthCode()`를 호출해 인증 코드를 발급해요. 발급된 `code`는 파트너 서버로 전달하고, 파트너 서버에서 사용자 식별키로 교환해요.
> [사용자 식별키 인증 코드 발급하기](/documentation/sdk/domains-api/user/user.createanonymouskeyauthcode.md)
>
> SDK를 통해 사용자 식별키 인증 코드를 발급할 수 있어요.
{% hint style="warning" %}
인증 코드는 짧은 시간 동안만 유효해요. 코드를 저장해 두고 나중에 재사용하지 말고, 발급받은 즉시 파트너 서버로 전달해 주세요.
{% endhint %}
***
### 2. 파트너 서버에서 인증 코드 교환하기
파트너 서버는 미니앱에서 받은 `code`를 앱인토스 파트너 API로 교환해요.\
교환에 성공하면 해당 미니앱 안에서 사용자를 구분하는 사용자 식별키(`anonKey`)를 받을 수 있어요.
이 API는 서버에서만 호출해 주세요. 파트너 API를 호출하려면 앱인토스 파트너 API용 mTLS 인증서가 필요해요.
> [사용자 식별 키 교환](/api/user-key.md)
>
> 사용자 식별 키 관련 파트너 API 스펙과 응답 형식을 확인할 수 있어요.
***
### 구현할 때 주의할 점
* 미니앱에서 받은 `code`는 파트너 서버로만 전달해 주세요.
* 파트너 서버는 클라이언트가 직접 보낸 `anonKey`를 신뢰하지 말고, 코드 교환 API로 받은 `anonKey`를 사용해 주세요.
* 교환에 성공한 코드는 다시 사용할 수 없어요. 같은 코드로 재시도하면 실패 응답이 내려와요.
* 코드가 만료되거나 유효하지 않으면 미니앱에서 인증 코드를 다시 발급받아 주세요.
* `anonKey`는 미니앱별로 고유해요. 같은 사용자라도 다른 미니앱에서는 다른 값이 내려올 수 있어요.
---
# 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 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/guide/authentication/anonymous-key-auth-code.md?ask=&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 `automate deployments from our CI pipeline` 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.
