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

# 사용자 식별키 발급

사용자 식별키 발급은 별도의 서버 연동이나 사용자 동의 절차 없이도 미니앱 안에서 사용자를 안정적으로 식별할 수 있도록 돕는 기능이에요.

사용자가 미니앱에 들어오는 순간 해당 사용자의 미니앱 준회원이 생성돼요. 미니앱은 이 사용자를 기준으로 서비스 이용 데이터, 저장 데이터, 랭킹, 포인트 같은 정보를 관리할 수 있어요.

{% hint style="info" %}
**토스 로그인 마이그레이션**

기존에 토스 로그인으로 사용자를 식별하고 있었다면, 사용자 식별키 발급 방식으로 전환할 수 있어요. 별도의 로그인 화면이나 서버 연동 없이 사용자 식별이 필요한 경우에 적합해요.
{% endhint %}

## 사용자 식별키란 <a href="#what-is-user-identifier-key" id="what-is-user-identifier-key"></a>

사용자 식별키는 미니앱 안에서 한 사용자를 구분하기 위한 고유 키 값이에요. 사용자의 개인 정보를 직접 노출하지 않고, 미니앱 내부에서 동일 사용자를 안정적으로 알아볼 수 있도록 해요.

반환되는 사용자 식별자는 미니앱별로 고유해요. 같은 토스 사용자라도 서로 다른 미니앱에서는 다른 식별키가 사용돼요.

{% hint style="info" %}
**꼭 확인해 주세요**

* 같은 미니앱 안에서는 동일한 사용자에게 항상 같은 식별키가 반환돼요.
* 앱 삭제나 기기 변경이 있더라도 동일한 사용자라면 같은 식별키가 반환돼요.
* 미니앱 유형에 맞는 발급 방식을 사용해야 해요. 다른 유형에서 사용하면 오류가 발생할 수 있어요.
* 샌드박스에서는 mock 데이터가 반환돼요. 실제 동작은 QR 코드로 토스앱에서 테스트해 주세요.
  {% endhint %}

## 미니앱 유형별 사용 방식 <a href="#usage-by-miniapp-type" id="usage-by-miniapp-type"></a>

미니앱 유형에 따라 사용자 식별키를 발급받는 방식이 달라요.

| 미니앱 유형 | 용도            | 설명                                                |
| ------ | ------------- | ------------------------------------------------- |
| 게임     | 게임 사용자 식별     | 게임 데이터, 랭킹, 포인트, 세이브 데이터 등을 사용자 단위로 관리할 때 사용해요.   |
| 비게임    | 일반 미니앱 사용자 식별 | 서비스 이용 기록, 사용자별 설정, 저장 데이터 등을 사용자 단위로 관리할 때 사용해요. |

## 게임 미니앱 <a href="#game-miniapp" id="game-miniapp"></a>

게임 미니앱에서는 게임 안에서 사용자를 식별하기 위한 전용 방식으로 사용자 식별키를 발급받아요. 토스 로그인처럼 별도의 인증 화면을 띄우지 않아도, 게임 미니앱 내부에서 고유한 사용자 식별자를 사용할 수 있어요.

이 식별키는 해당 게임 미니앱 안에서만 유효해요. 게임 내 데이터 저장, 랭킹 관리, 포인트 관리, 세이브 데이터 관리처럼 사용자를 기준으로 이어져야 하는 데이터에 사용할 수 있어요.

{% hint style="warning" %}
**주의하세요**

* 게임 미니앱에서만 사용할 수 있어요.
* 지원 버전보다 낮은 토스앱에서는 사용자 식별키가 제공되지 않을 수 있어요.
* 모든 사용자의 식별자를 안정적으로 제공하기 위해 게임 미니앱의 최소 지원 토스앱 버전이 상향됐어요.
* 지원 버전 미만에서는 미니앱 진입 시 업데이트 안내 화면이 표시돼요.
* 샌드박스 환경에서는 mock 데이터가 내려와요. 실제 동작은 QR 코드로 토스앱에서 테스트해 주세요.
  {% endhint %}

## 비게임 미니앱 <a href="#non-game-miniapp" id="non-game-miniapp"></a>

비게임 미니앱에서는 일반 서비스 안에서 사용자를 식별하기 위한 방식으로 사용자 식별키를 발급받아요. 별도의 인증 화면이나 서버 연동 없이, 미니앱 내부에서 고유한 사용자 식별자를 사용할 수 있어요.

이 식별키는 해당 미니앱 안에서만 유효해요. 사용자별 설정, 이용 기록, 저장 데이터처럼 사용자를 기준으로 관리해야 하는 데이터에 사용할 수 있어요.

{% hint style="warning" %}
**주의하세요**

* 비게임 미니앱에서만 사용할 수 있어요.
* 지원 버전보다 낮은 환경에서는 사용자 식별키가 제공되지 않을 수 있어요.
* 반환되는 사용자 식별키는 토스 서버 API 호출용 키가 아니에요.
* 내부 사용자 식별과 데이터 관리 용도로만 사용해 주세요.
* 샌드박스 환경에서는 mock 데이터가 내려와요. 실제 동작은 QR 코드로 토스앱에서 테스트해 주세요.
  {% endhint %}

## 사용자 식별키 활용 예시 <a href="#user-identifier-key-examples" id="user-identifier-key-examples"></a>

사용자 식별키는 미니앱 내부에서 사용자를 기준으로 데이터를 이어서 관리해야 할 때 사용할 수 있어요.

* 사용자의 서비스 이용 기록 관리
* 사용자별 설정 저장
* 게임 랭킹, 포인트, 세이브 데이터 관리
* 재방문 사용자의 이전 상태 복원
* 로그인 없이 제공하는 개인화 경험 구성

{% hint style="info" %}
사용자 식별키는 사용자를 구분하기 위한 값이에요. 사용자의 실명, 전화번호, 계정 정보 같은 개인 정보를 대신 제공하는 기능은 아니에요.
{% endhint %}

## 개발하기 <a href="#development" id="development"></a>

비게임 미니앱에서 사용자 식별키를 발급받는 방법은 [User.getAnonymousKey](https://developers-apps-in-toss.toss.im/documentation/sdk/domains-api/user/user.getanonymouskey)에서 확인해 주세요.


---

# 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/anon-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 `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.