> 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/documentation/api-and-sdk-en/common/authentication/hash-key.md).

# Issue user identification key

User identifier key issuance is a feature that helps you reliably identify users within a mini app without a separate server or user consent process.

{% hint style="info" %}
**Toss Login Migration**

If you were already identifying users with Toss Login, you can switch to user identifier key issuance. Please refer to the migration guide.
{% endhint %}

The function you use depends on the mini app type.

| Mini app type | Function            | Description                                                    |
| ------------- | ------------------- | -------------------------------------------------------------- |
| Game          | `getUserKeyForGame` | Returns a user identifier key dedicated to game mini apps.     |
| Non-game      | `getAnonymousKey`   | Returns a user identifier key dedicated to non-game mini apps. |

Both functions return a **unique key value (hash)** that can identify users without server integration. The returned user identifier is unique per mini app.

{% hint style="info" %}
**Please make sure to check**

* The unique key value (`hash`) always returns the same value for the same user within the same mini app.
* Each function can only be used in mini apps of the corresponding category. Calling it in the wrong category will cause an error.
* In the sandbox, mock data is returned, so please test using a QR code.
  {% endhint %}

***

### Game mini app

**SDK function:** `getUserKeyForGame`

`getUserKeyForGame`is a dedicated API for identifying users in game mini apps. Unlike Toss Login, you can get a unique user identifier directly inside the game mini app without a separate authentication screen or server integration.

This function **can only be used in game-category mini apps**and the returned user identifier (`hash`) is **unique per mini app (game)**This value can be used for in-game data storage, ranking management, and more.

{% hint style="info" %}
**Be careful**

* This function **can only be used in game-category mini apps**If you call it in a non-game mini app, `'INVALID_CATEGORY'`is returned.
* **Toss app 5.232.0 or later**is supported only on. On earlier versions, `undefined`is returned.
* To provide identifiers for all users reliably, **the minimum supported Toss app version for game mini apps has been raised to 5.232.0.**.
  * If the version is below the supported version, an update notice screen is shown when entering the mini app.
* The returned user key is **not a key for calling Toss server APIs.**
  * Please use it only for internal user identification and data management within the game company.
* In the sandbox environment, **mock data**is returned. Please test the actual behavior in the Toss app via QR code.
  {% endhint %}

**Signature**

```typescript
function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
```

**Return value**

* `Promise<GetUserKeyForGameSuccessResponse | 'INVALID\_CATEGORY' | 'ERROR' | undefined>`

  Returns the result of user key lookup.
* `GetUserKeyForGameSuccessResponse`: User key lookup succeeded. `{ type: 'HASH', hash: string }` Returns in this form.
  * `hash` The value is a user identifier that is only valid in the corresponding game mini app.
* `'INVALID_CATEGORY'`: Called from a mini app that is not in the game category.
* `'ERROR'`: An unknown error occurred.
* `undefined`: The app version is lower than the minimum supported version.

**Example: Get game user identifier**

The example below shows the basic flow in a game mini app `getUserKeyForGame`for calling it and receiving the user identifier and handling it.

{% tabs %}
{% tab title="js" %}

```js
import { getUserKeyForGame } from '@apps-in-toss/web-framework';

async function handleGetUserKey() {
  const result = await getUserKeyForGame();

  if (!result) {
    console.warn('This app version is not supported.');
  } else if (result === 'INVALID_CATEGORY') {
    console.error('This mini app is not in the game category.');
  } else if (result === 'ERROR') {
    console.error('An error occurred while looking up the user key.');
  } else if (result.type === 'HASH') {
    console.log('User key:', result.hash);
    // You can manage game data using the user key here.
  }
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { getUserKeyForGame } from '@apps-in-toss/web-framework';

function GameUserKeyButton() {
  async function handleClick() {
    const result = await getUserKeyForGame();

    if (!result) {
      console.warn('This app version is not supported.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This mini app is not in the game category.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An error occurred while looking up the user key.');
      return;
    }

    if (result.type === 'HASH') {
      console.log('User key:', result.hash);
      // You can manage game data using the user key here.
    }
  }

  return <button onClick={handleClick}>Get user key</button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Button } from 'react-native';
import { getUserKeyForGame } from '@apps-in-toss/framework';

function GameUserKeyButton() {
  async function handlePress() {
    const result = await getUserKeyForGame();

    if (!result) {
      console.warn('This app version is not supported.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This mini app is not in the game category.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An error occurred while looking up the user key.');
      return;
    }

    if (result.type === 'HASH') {
      console.log('User key:', result.hash);
      // You can manage game data using the user key here.
    }
  }

  return <Button onPress={handlePress} title="Get user key" />;
}
```

{% endtab %}
{% endtabs %}

**Notes**

* `getUserKeyForGame`is a login/identification method dedicated to game mini apps.
* Unlike Toss Login (`appLogin`), it can be used without server API integration.
* We recommend managing game user data (rankings, points, save data, etc.) based on this user key.

***

### Non-game mini app

**SDK function:** `getAnonymousKey`

`getAnonymousKey`is an API for identifying users in non-game mini apps. Like Toss Login, you can get a unique user identifier directly inside the mini app without a separate authentication screen or server integration.

This function **Can only be used in non-game category mini apps**and the returned user identifier (`hash`) is **Unique per mini app**.

{% hint style="info" %}
**Be careful**

* This function **Can only be used in non-game category mini apps**If you call it in a game mini app, `'INVALID_CATEGORY'`is returned.
* **SDK 2.4.5 or later**is supported. On earlier versions, `undefined`is returned.
* The returned user key is **not a key for calling Toss server APIs.**
  * Please use it only for internal user identification and data management.
* In the sandbox environment, **mock data**is returned. Please test the actual behavior in the Toss app via QR code.
  {% endhint %}

**Signature**

```typescript
function getAnonymousKey(): Promise<GetAnonymousKeySuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
```

**Return value**

* `Promise<GetAnonymousKeySuccessResponse | 'INVALID\_CATEGORY' | 'ERROR' | undefined>`

  Returns the result of user key lookup.
* `GetAnonymousKeySuccessResponse`: User key lookup succeeded. `{ type: 'HASH', hash: string }` Returns in this form.
  * `hash` The value is a user identifier that is only valid in the corresponding mini app.
* `'INVALID_CATEGORY'`: Called from a mini app that is not in the non-game category.
* `'ERROR'`: An unknown error occurred.
* `undefined`: The SDK version is lower than the minimum supported version.

**Example: Get user identifier**

The example below shows the basic flow in a non-game mini app `getAnonymousKey`for calling it and receiving the user identifier and handling it.

{% tabs %}
{% tab title="js" %}

```js
import { getAnonymousKey } from '@apps-in-toss/web-framework';

async function handleGetUserKey() {
  const result = await getAnonymousKey();

  if (!result) {
    console.warn('This SDK version is not supported.');
  } else if (result === 'INVALID_CATEGORY') {
    console.error('This mini app is not in the non-game category.');
  } else if (result === 'ERROR') {
    console.error('An error occurred while looking up the user key.');
  } else if (result.type === 'HASH') {
    console.log('User key:', result.hash);
    // You can manage data using the user key here.
  }
}
```

{% endtab %}

{% tab title="React" %}

```tsx
import { getAnonymousKey } from '@apps-in-toss/web-framework';

function UserKeyButton() {
  async function handleClick() {
    const result = await getAnonymousKey();

    if (!result) {
      console.warn('This SDK version is not supported.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This mini app is not in the non-game category.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An error occurred while looking up the user key.');
      return;
    }

    if (result.type === 'HASH') {
      console.log('User key:', result.hash);
      // You can manage data using the user key here.
    }
  }

  return <button onClick={handleClick}>Get user key</button>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { Button } from 'react-native';
import { getAnonymousKey } from '@apps-in-toss/framework';

function UserKeyButton() {
  async function handlePress() {
    const result = await getAnonymousKey();

    if (!result) {
      console.warn('This SDK version is not supported.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This mini app is not in the non-game category.');
      return;
    }

    if (result === 'ERROR') {
      console.error('An error occurred while looking up the user key.');
      return;
    }

    if (result.type === 'HASH') {
      console.log('User key:', result.hash);
      // You can manage data using the user key here.
    }
  }

  return <Button onPress={handlePress} title="Get user key" />;
}
```

{% endtab %}
{% endtabs %}

**Notes**

* `getAnonymousKey`is a user identification method dedicated to non-game mini apps.
* Unlike Toss Login (`appLogin`), it can be used without server API integration.
* We recommend managing user data based on this user key.

***

### Verify identifier key

Use it to verify whether the user identifier key is valid.

**Basic information**

| Item                  | Value                              |
| --------------------- | ---------------------------------- |
| Base URL              | `https://apps-in-toss-api.toss.im` |
| Server authentication | mTLS (client certificate)          |
| Content-Type          | `application/json`                 |

{% hint style="info" %}
**mTLS certificates are required for server-to-server communication**

The identifier key verification API is server-to-server communication from the partner server to the Apps in Toss server. For security, configure an mTLS certificate on your server before calling it. For how to issue a certificate, see [How to issue an mTLS certificate](https://developers-apps-in-toss.toss.im/documentation/integration/getting-started).
{% endhint %}

* Method: `POST`
* Endpoint: `/api-partner/v1/apps-in-toss/users/anon-key/verify`

**Request headers**

| Name         | Type   | Required | Description                                                                                                                                     |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-anon-key` | string | Y        | [User identifier key issuance](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)received with `hash` value. |

```bash
curl -X 'POST' \
  'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/users/anon-key/verify' \
  -H 'accept: application/json' \
  -H 'x-anon-key: anon-key' \
  -d ''
```

**Response parameters**

| Name    | Type   | Description                                                                                                         |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| success | string | Indicates whether the identifier key is valid. If valid, `"true"`, and if not valid, an error response is returned. |

```json
{
  "resultType": "SUCCESS",
  "success": "true"
}
```

**Error codes**

This is a list of error codes that may occur while using the API. Please refer to the response code or message and **apply appropriate exception handling logic**.

| Code  | Message                                                                |
| ----- | ---------------------------------------------------------------------- |
| `401` | The user identifier key is missing, or the mapped user cannot be found |


---

# 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/documentation/api-and-sdk-en/common/authentication/hash-key.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.