> 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 Identifier Key

User key issuance is a feature that helps identify users reliably inside the mini app without separate server integration or user consent procedures.\
The moment a user enters the mini app, that user's mini app provisional member is created.

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

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

The function you use varies depending 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 to each mini app.

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

* Unique key value (`hash`) always returns the same value for the same user within the same mini app.
* Even if the app is deleted or the device is changed, the same value is returned for the same user.
* Each function can only be used in mini apps of the corresponding category. If called from the wrong category, an error occurs.
* In the sandbox, mock data is returned, so please test with a QR code.
  {% endhint %}

***

### Game mini app

**SDK function:** `getUserKeyForGame`

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

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

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

* This function is **available only in game category mini apps**If called from a non-game mini app, `'INVALID_CATEGORY'`is returned.
* **Toss app 5.232.0 or later**is supported only on. Below that version, `undefined`is returned.
* To reliably provide identifiers for all users, **the minimum supported Toss app version for game mini apps has been raised to 5.232.0.**has been raised.
  * For versions below the supported version, an update prompt screen is shown when entering the mini app.
* 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 user key lookup result.
* `GetUserKeyForGameSuccessResponse`: User key lookup succeeded. `{ type: 'HASH', hash: string }` is returned in this format.
  * `hash` The value is a user identifier valid only 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`of calling it to receive and handle a user identifier.

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

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

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

  if (!result) {
    console.warn('Unsupported app version.');
  } else if (result === 'INVALID_CATEGORY') {
    console.error('This is a mini app that 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);
    // Here you can manage game data using the user key.
  }
}
```

{% 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('Unsupported app version.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This is a mini app that 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);
      // Here you can manage game data using the user key.
    }
  }

  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('Unsupported app version.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This is a mini app that 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);
      // Here you can manage game data using the user key.
    }
  }

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

{% endtab %}
{% endtabs %}

**Notes**

* `getUserKeyForGame`This 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 (ranking, points, save data, etc.) based on this user key.

***

### Non-game mini app

**SDK function:** `getAnonymousKey`

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

This function is **available only in non-game category mini apps**and the returned user identifier (`hash`) is **unique to each mini app**it is.

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

* This function is **available only in non-game category mini apps**If called from a game mini app, `'INVALID_CATEGORY'`is returned.
* **SDK 2.4.5 or later**is supported. Below that version, `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 user key lookup result.
* `GetAnonymousKeySuccessResponse`: User key lookup succeeded. `{ type: 'HASH', hash: string }` is returned in this format.
  * `hash` The value is a user identifier valid only 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 of calling `getAnonymousKey`it to receive and handle a user identifier in a non-game mini app.

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

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

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

  if (!result) {
    console.warn('Unsupported SDK version.');
  } else if (result === 'INVALID_CATEGORY') {
    console.error('This is a mini app that 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);
    // Here you can manage data using the user key.
  }
}
```

{% 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('Unsupported SDK version.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This is a mini app that 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);
      // Here you can manage data using the user key.
    }
  }

  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('Unsupported SDK version.');
      return;
    }

    if (result === 'INVALID_CATEGORY') {
      console.error('This is a mini app that 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);
      // Here you can manage data using the user key.
    }
  }

  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

Used 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" %}
**An mTLS certificate is required for server-to-server communication**

The identifier key verification API is server-to-server communication from a partner server to the Apps in Toss server. For security, set up an mTLS certificate on the server before calling it. For how to issue the certificate, see [How to issue an mTLS certificate](https://developers-apps-in-toss.toss.im/documentation/integration/getting-started)Please refer to
{% 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        | [The value](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)received through `hash` user identifier key issuance. |

```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"`, if invalid, 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. Refer to the response code or message and apply **appropriate exception handling logic**please.

| Code  | Message                                                                   |
| ----- | ------------------------------------------------------------------------- |
| `401` | The user identifier key does not exist 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.