Issue User Identification 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.

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.

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.

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.

---

Game mini app

SDK function: getUserKeyForGame

getUserKeyForGameThis 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 appsand the returned user identifier (hash) is unique to each game mini appIt can be used for in-game data storage, ranking management, etc.

Be careful

• This function is available only in game category mini appsIf called from a non-game mini app, 'INVALID_CATEGORY'is returned.
• Toss app 5.232.0 or lateris supported only on. Below that version, undefinedis 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 datais returned. Please test the actual behavior in the Toss app via QR code.

Signature

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 getUserKeyForGameof calling it to receive and handle a user identifier.

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.
  }
}

React

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>;
}

React Native

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" />;
}

Notes

• getUserKeyForGameThis 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

getAnonymousKeyThis 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 appsand the returned user identifier (hash) is unique to each mini appit is.

Be careful

• This function is available only in non-game category mini appsIf called from a game mini app, 'INVALID_CATEGORY'is returned.
• SDK 2.4.5 or lateris supported. Below that version, undefinedis 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 datais returned. Please test the actual behavior in the Toss app via QR code.

Signature

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 getAnonymousKeyit to receive and handle a user identifier in a non-game mini app.

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.
  }
}

React

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>;
}

React Native

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" />;
}

Notes

• getAnonymousKeyis 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

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 certificatePlease refer to

• 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 valuereceived through hash user identifier key issuance.

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.

{
  "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 logicplease.

Code	Message
401	The user identifier key does not exist or the mapped user cannot be found