Toss 登录

服务介绍和控制台设置方法是 Toss 登录介绍文档请参考。

基本信息

项目	值
Base URL	https://apps-in-toss-api.toss.im
服务器认证	mTLS（客户端证书）
Content-Type	application/json

服务器间通信需要 mTLS 证书

Toss 登录 API 是从合作方服务器调用到 Apps in Toss 服务器的服务器间通信。为保障安全，请先在服务器上配置 mTLS 证书后再调用。证书发放方法是 mTLS 证书发放方法。

---

1. 获取授权码

SDK 函数： appLogin

appLogin使用 Toss App 的认证流程执行登录，登录成功后返回授权码(authorizationCode）作为返回值。

请注意

• 此步骤 客户端（迷你应用） 只负责获取授权码。
• 获取授权码之后的 token 交换 / AccessToken 发放 / 用户信息查询必须在 服务器上处理。
• 授权码的有效时间为 10分钟。
• 授权码是 一次性的，重复使用会失败。
• authorizationCode请不要在客户端长期保存。
• 敏感信息(AccessToken, RefreshToken 等）应 在服务器上安全保管。

首次进行 Toss 登录时 appLogin 调用该函数后会打开 Toss 登录窗口，并显示在 Apps in Toss 控制台中注册的条款同意页面。用户同意必需条款后会返回授权码。

已进行过 Toss 登录时 appLogin 调用该函数后无需额外登录窗口即可直接返回授权码。

签名

function appLogin(): Promise<{
  authorizationCode: string;
  referrer: 'DEFAULT' | 'SANDBOX';
}>;

返回值

• authorizationCode string

  这是在用户认证完成后发放的授权码。将其传到服务器并交换为 AccessToken。
• referrer string

  表示登录请求是在什么环境中发生的。DEFAULT：实际 Toss App 环境，SANDBOX：沙箱环境

示例：通过 Toss 认证进行登录的示例

js

import { appLogin } from '@apps-in-toss/web-framework';

async function handleLogin() {
  const { authorizationCode, referrer } = await appLogin();

  // 将获取到的授权码(`authorizationCode`)和 `referrer` 传给服务器。
}

React

import { appLogin } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function Page() {
  async function handleLogin() {
    const { authorizationCode, referrer } = await appLogin();

    // 将获取到的授权码(`authorizationCode`)和 `referrer` 传给服务器。
  }

  return (
    <Button size="medium" onClick={handleLogin}>
      登录
    </Button>
  );
}

React Native

import { appLogin } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function Page() {
  async function handleLogin() {
    const { authorizationCode, referrer } = await appLogin();

    // 将获取到的授权码(`authorizationCode`)和 `referrer` 传给服务器。
  }

  return <Button onPress={handleLogin}>登录</Button>;
}

体验示例应用

apps-in-toss-examples 在仓库中 with-app-login 下载代码并试用。

---

2. 获取 AccessToken

用于调用用户信息查询 API 的 发放访问令牌。

• Content-Type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/user/oauth2/generate-token

请参考

AccessToken 的有效时间为 1 小时。

请求

名称	类型	是否必填	说明
authorizationCode	string	Y	授权码
referrer	string	Y	referrer

成功响应

名称	类型	是否必填	说明
tokenType	string	Y	固定为 bearer
accessToken	string	Y	accessToken
refreshToken	string	Y	refreshToken
expiresIn	string	Y	过期时间（秒）
scope	string	Y	已授权的 scope（区分）

{
  "resultType": "SUCCESS",
  "success": {
    "accessToken": "eyJraWQiOiJjZXJ0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjMzBdseY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLzz9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw",
    "refreshToken": "xNEYPASwWw0n1AxZUHU9KeGj8BitDyYo4wi8rpfkUcJwByVxpAdUzwtIaWGVL6vHdrXLCxIlHAQRPF9hHnFleTsHkqUXzc-_78sD_r1Uh5Ff9UCYfArx8LTn1Vk99dDb",
    "scope": "user_ci user_birthday user_nationality user_name user_phone user_gender",
    "tokenType": "Bearer",
    "expiresIn": 3599
  }
}

失败响应 当授权码已过期，或使用同一授权码重复请求 AccessToken 时

{
  "error": "invalid_grant"
}

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "INTERNAL_ERROR",
    "reason": "处理请求时发生了问题。"
  }
}

3. 重新获取 AccessToken

重新发放用于调用用户信息查询 API 的访问令牌。

• Content-type : application/json
• Method : POST
• URL : /api-partner/v1/apps-in-toss/user/oauth2/refresh-token

请参考

refreshToken 的有效时间为 14 天。

请求

名称	类型	是否必填	说明
refreshToken	string	Y	已发放的 RefreshToken

成功响应

名称	类型	是否必填	说明
tokenType	string	Y	固定为 bearer
accessToken	string	Y	accessToken
refreshToken	string	Y	refreshToken
expiresIn	string	Y	过期时间（秒）
scope	string	Y	已授权的 scope（区分）

失败响应

名称	类型	是否必填	说明
errorCode	string	Y	错误代码
reason	string	Y	错误消息

4. 获取用户信息

查询用户信息。 DI是 null会返回，并且可无限次调用。为保护个人信息，所有个人信息都以 加密形式提供。

• Content-type : application/json
• Method : GET
• URL : /api-partner/v1/apps-in-toss/user/oauth2/login-me

scope 中 user_key 值将会追加

scope 参数为 控制台中选择的项目里，仅返回用户同意的值。 返回。 从 2026 年 1 月 2 日起 scope 值中 user_key 将追加项目。 由于新增 scope 可能包含之前未定义的值， 请注意处理 scope 时不要发生异常。

请求头

名称	类型	是否必填	说明
Authorization	string	Y	使用 AccessToken 进行认证请求 Authorization: Bearer ${AccessToken}

成功响应

名称	类型	是否必填	是否加密	说明
userKey	number	Y	N	这是仅能在该应用中使用的用户唯一标识值。即使是同一用户，如果应用不同，userKey 也可能不同。
scope	string	Y	N	已授权的 scope 列表。包含控制台中选择的项目里用户同意的值和 user_key 项目。
agreedTerms	list	Y	N	用户同意的条款列表。
name	string	N	Y	用户姓名。
phone	string	N	Y	用户手机号码。
birthday	string	N	Y	用户出生日期。（yyyyMMdd）
ci	string	N	Y	用户 CI 值。
di	string	N	Y	始终 null 值返回。
gender	string	N	Y	用户性别信息。（MALE/FEMALE）
nationality	string	N	Y	用户是否为本国人/外国人信息。（LOCAL/FOREIGNER）
email	string	N	Y	用户邮箱信息。该值未进行归属认证。

userKey 按应用单独发放

userKey 是仅在该应用中有效的标识。同一用户如果应用不同，会发放不同的 userKey。

{
  "resultType": "SUCCESS",
  "success": {
    "userKey": 443731104,
    "scope": "user_ci,user_birthday,user_nationality,user_name,user_phone,user_gender, user_key",
    "agreedTerms": ["terms_tag1", "terms_tag2"],
    "name": "ENCRYPTED_VALUE",
    "phone": "ENCRYPTED_VALUE",
    "birthday": "ENCRYPTED_VALUE",
    "ci": "ENCRYPTED_VALUE",
    "di": null,
    "gender": "ENCRYPTED_VALUE",
    "nationality": "ENCRYPTED_VALUE",
    "email": null
  }
}

失败响应 如果使用无效令牌，请确认当前使用中的 access_token 的有效时间并重新发放。

{
  "error": "invalid_grant"
}

服务器错误响应示例

errorCode	说明
INTERNAL_ERROR	内部服务器错误
USER_KEY_NOT_FOUND	无法找到接入登录服务的用户 key 值
USER_NOT_FOUND	无法找到 Toss 用户信息
BAD_REQUEST_RETRIEVE_CERT_RESULT_EXCEEDED_LIMIT	查询次数超限，使用同一令牌 /api/login/user/me/without-di 查询 API 后可以正常查询，但 di 字段会以 null 值返回

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "INTERNAL_ERROR",
    "reason": "处理请求时发生了问题。"
  }
}

5. 解密用户信息

通过控制台邮箱收到的 解密密钥和 AAD(Additional Authenticated DATA) 进行。

加密算法

• AES 对称密钥加密
• 密钥长度：256 位
• 模式：GCM
• AAD：与解密密钥一起通过电子邮件发送给您。

数据交换方式

• 加密数据的前半部分包含 IV(NONCE)。
• 解密时必须从密文中提取 IV 才能正常解密。

解密示例代码

Kotlin 示例

import java.util.Base64
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

class Test {
    fun decrypt(
        encryptedText: String,
        base64EncodedAesKey: String,
        add: String,
    ): String {
        val IV_LENGTH = 12
        val decoded = Base64.getDecoder().decode(encryptedText)
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        val keyByteArray = Base64.getDecoder().decode(base64EncodedAesKey)
        val key = SecretKeySpec(keyByteArray, "AES")
        val iv = decoded.copyOfRange(0, IV_LENGTH)
        val nonceSpec = GCMParameterSpec(16 * Byte.SIZE_BITS, iv)

        cipher.init(Cipher.DECRYPT_MODE, key, nonceSpec)
        cipher.updateAAD(add.toByteArray())

        return String(cipher.doFinal(decoded, IV_LENGTH, decoded.size - IV_LENGTH))
    }
}

PHP 示例

<?php

class Test {
    public function decrypt($encryptedText, $base64EncodedAesKey, $add) {
        $IV_LENGTH = 12;
        $decoded = base64_decode($encryptedText);
        $keyByteArray = base64_decode($base64EncodedAesKey);
        $iv = substr($decoded, 0, $IV_LENGTH);
        $ciphertext = substr($decoded, $IV_LENGTH);

        $tag = substr($ciphertext, -16);
        $ciphertext = substr($ciphertext, 0, -16);

        $decrypted = openssl_decrypt(
            $ciphertext,
            'aes-256-gcm',
            $keyByteArray,
            OPENSSL_RAW_DATA,
            $iv,
            $tag,
            $add
        );

        return $decrypted;
    }
}


// 使用示例
$test = new Test();
$encryptedText = "Encrypted Text"; // 输入 Encrypted Text
$base64EncodedAesKey = "Key"; // 输入 Key
$add = "TOSS";

$result = $test->decrypt($encryptedText, $base64EncodedAesKey, $add);
echo $result;

?>

JAVA 示例

public class Test {
    public String decrypt(
        String encryptedText,
        String base64EncodedAesKey,
        String add
    ) throws Exception {
        final int IV_LENGTH = 12;
        byte[] decoded = Base64.getDecoder().decode(encryptedText);
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        byte[] keyByteArray = Base64.getDecoder().decode(base64EncodedAesKey);
        SecretKeySpec key = new SecretKeySpec(keyByteArray, "AES");
        byte[] iv = new byte[IV_LENGTH];
        System.arraycopy(decoded, 0, iv, 0, IV_LENGTH);
        GCMParameterSpec nonceSpec = new GCMParameterSpec(16 * Byte.SIZE, iv);

        cipher.init(Cipher.DECRYPT_MODE, key, nonceSpec);
        cipher.updateAAD(add.getBytes());

        byte[] decrypted = cipher.doFinal(decoded, IV_LENGTH, decoded.length - IV_LENGTH);
        return new String(decrypted);
    }
}

6. 断开登录

如果不再使用已发放的 AccessToken，或因用户请求需要使令牌失效，请删除（使其失效）令牌。

• Content-type : application/json
• Method : POST
• URL :

  • 通过 accessToken 断开连接： /api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token
  • 通过 userKey 断开连接： /api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key

通过 AccessToken 断开登录连接

// 格式
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token'

// 示例
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJjZXJ0IizzYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJtMHVmMmhaUmpJTnNEQTdLNHVuVHhMb3IwcWNSa2JNPSIsImF1ZCI6IjNlenQ2ZTF0aDg2b2RheTlwOWN1eTg0dTRvdm5nNnNzIiwibmJmIjoxNzE4MjU0ODM2LCJzY29wZSI6WyJ1c2VyX2NpIiwidXNlcl9iaXJ0aGRheSIsInVzZXJfbmF0aW9uYWxpdHkiLCJ1c2VyX25hbWUiLCJ1c2VyX3Bob25lIiwidXNlcl9nZW5kZXIiXSwiaXNzIjoiaHR0cHM6Ly9jZXJ0LnRvc3MuaW0iLCJleHAiOjE3MTgyNTg0MzYsImlhdCI6MTcxODI1NDgzNiwianRpIjoiMTJkYjYwZjYtMjEzYS00NWQ3LTllOTItODBjMzBmY2JkMGQ3In0.W1cjoeMN8pd3Jqgh6h8YzSVQ1PUNldulJJgy6bgH1AoDbv5xFTlBLwk9Slb_u52zUpyZbhglwblQmNJs7GT6-us7XtfxSGxTUY3ORqIhF_PPGQ6soi_Qgsi-hmX165CCAilf8cltSTTuTt8xOiEbLuSTY-cecxo7SkPUonQ_0v4_Ik0kwOiOBuYZyuch3KmlYQZTqsJmxlwJAPB8M9tZTtDpLOv9MEPU35YS7CZyN0l7lwn1EKrDHJdzA5CnstqEdz2I0eREmMgZoG9mSEybgD4NtPmVJos6AJerUGgSmzP_TwwlybVATuGpnAUmH1idaZJ-MHZJhUhR82z4zTn3bw'

通过 userKey 断开登录连接

请参考

如果一个 userKey 关联了很多 AccessToken 可能会发生 readTimeout（3 秒） 。这种情况下请不要重试请求，请在一段时间后再试。

// 格式
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $access_token' \
--data '{"userKey": $user_key}'

// 示例
curl --request POST 'https://apps-in-toss-api.toss.im/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key' \
--header 'Content-Type: application/json' \
--data '{"userKey": 443731103}'

{
  "resultType": "SUCCESS",
  "success": {
    "userKey": 443731103
  }
}

7. 通过回调断开登录

当用户在 Toss App 内解除与服务的连接时，会通知到商家服务器。如需对已断开连接的用户进行处理，可以使用此功能。可在控制台中输入接收回调的 URL 和 basic Auth 标头。

请务必确认

如果在服务中直接调用断开登录连接 API， 则不会触发回调。

GET 方式

• 请求 requestParam 中 userKey和 referrer包含

// 格式
curl --request GET '$callback_url?userKey=$userKey&referrer=$referrer'

// 示例
curl --request GET '$callback_url?userKey=443731103&referrer=UNLINK'

POST 方式

• 请求 body 中 userKey和 referrer包含

// 格式
curl --request POST '$callback_url' \
--header 'Content-Type: application/json' \
--data '{"userKey": $user_key, "referrer": $referrer}'

// 示例
curl --request POST '$callback_url' \
--header 'Content-Type: application/json' \
--data '{"userKey": 443731103, "referrer": "UNLINK"}'

referrer 是断开连接请求路径。

referrer	说明
UNLINK	当用户在 Toss App 中直接断开连接时调用。（路径：Toss App → 设置 → 认证与安全 → 使用 Toss 登录的服务 → '断开连接'）
WITHDRAWAL_TERMS	当用户撤回登录服务条款同意时调用。（路径：Toss App → 设置 → 法律信息及其他 → 条款及个人信息处理同意 → 按服务分类的同意内容："Toss 登录" → '撤回同意'）
WITHDRAWAL_TOSS	当用户注销 Toss 会员时调用。

故障排查

本地开发时发生认证错误时

本地开发时发生认证错误的原因主要有两种。

1. 认证令牌已过期 之前发放的认证令牌可能已过期。请获取新令牌后重试。
2. 开发者登录失败 可能是在沙箱环境中尚未使用开发者账号登录。请参考沙箱应用下载，完成登录后再试。