For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/server-api/login.md.

登录相关 API

阅读提示:本文是登录 OpenAPI 的接口字典,适合查询字段和示例。如果你还不清楚端侧如何取得 login_code、phone_code,或服务端如何完成账号绑定,请先阅读 登录接入(服务端)。

目标调用顺序服务端鉴权方式返回结果
仅获取用户标识直接使用 login_code 调用“获取用户 OpenID”请求体传 app_id 和 app_secret,不需要应用级 Tokenopen_id
获取用户手机号先获取应用级 Token,再使用 phone_code 调用“获取用户加密手机号”请求头传 x-DB-AccessTokenencrypt_phone_number 密文
调用其他应用级 OpenAPI先获取应用级 Token,再按目标接口要求调用请求头传应用级 Token以目标接口为准

login_code 和 phone_code 都是短时、一次性的端侧票据,服务端收到后应立即兑换。手机号密文必须在服务端解密;证书与解密方法参见 关于证书。

获取应用级别鉴权 Token

获取应用级 access_token,供业务服务端以应用身份调用需要应用级鉴权的 OpenAPI。本文中,“获取用户加密手机号”需要该 Token;“通过 login_code 获取用户 OpenID”不需要该 Token。

使用限制

  • 获取的 access_token 有有效期限制(以响应中 expires_in 字段返回的秒数为准),过期后需重新获取。
  • 不要为每次业务请求重新获取 Token。建议由服务端单一模块统一缓存,并按 expires_in 判断有效期;多实例部署时共享缓存或使用刷新锁,避免并发刷新。

接口说明

  • 业务场景:适用于服务端应用以自身身份调用豆包应用插件开放平台 API 的场景。登录流程中,获取用户手机号接口需要传入此 token 作为鉴权凭证。

  • 前提条件:需要在豆包应用插件开放平台完成应用创建,获取到 app_id 和 app_secret。

  • 注意事项:

    • app_secret 属于敏感信息,请妥善保管,切勿在客户端代码或公开环境中暴露。
    • grant_type 参数请填写固定值 client_credential。

基本信息

名称描述
HTTP Path/api/token/v1/developer/get_client_token
HTTP MethodPOST
Scope无需特殊 Scope
权限要求无需用户授权,使用应用自身凭证即可调用

请求头

名称类型必填描述
content-typestring是固定值 "application/json"

请求参数

Body

名称类型是否必填描述示例值
app_idstring是应用 ID,唯一标识一个三方应用。在豆包应用插件开放平台创建应用后获取。tt07e3715e218c94OR
app_secretstring是应用密钥,与 app_id 配对使用,用于验证应用身份。在豆包应用插件开放平台应用详情页获取。clt.943da17996fb5ceb******
grant_typestring是授权认证类型,固定值为 client_credential 。client_credential

请求示例

cURL:

curl -X POST 'https://hello.doubao-dev.com/api/token/v1/developer/get_client_token' \
  -H 'content-type: application/json' \
  -d '{
    "app_id": "tt07e3715e218c94OR",
    "app_secret": "your_app_secret",
    "grant_type": "client_credential"
  }'

Go:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://hello.doubao-dev.com/api/token/v1/developer/get_client_token"
    requestBody := map[string]string{
        "app_id":     "tt07e3715e218c94OR",
        "app_secret": "your_app_secret",
        "grant_type": "client_credential",
    }
    jsonData, _ := json.Marshal(requestBody)
    resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Java:

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GetClientToken {
    public static void main(String[] args) throws Exception {
        String url = "https://hello.doubao-dev.com/api/token/v1/developer/get_client_token";
        String requestBody = """
            {
                "app_id": "tt07e3715e218c94OR",
                "app_secret": "your_app_secret",
                "grant_type": "client_credential"
            }
            """;
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("content-type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Node.Js:

const axios = require('axios');

async function getClientToken() {
    const url = 'https://hello.doubao-dev.com/api/token/v1/developer/get_client_token';
    const data = {
        app_id: 'tt07e3715e218c94OR',
        app_secret: 'your_app_secret',
        grant_type: 'client_credential'
    };
    try {
        const response = await axios.post(url, data, {
            headers: { 'content-type': 'application/json' }
        });
        console.log(response.data);
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}
getClientToken();

响应参数

名称类型是否必填描述示例值
codeinteger是响应状态码,0 表示成功,非 0 表示失败。0
msgstring是响应状态描述信息。success
log_idstring是日志 ID,用于问题排查时提供给技术支持。20260309120000ABCDEF123456
dataobject是响应数据对象,详见下方 data 字段说明。-

data 字段说明

名称类型是否必填描述示例值
access_tokenstring是应用级别 token,后续调用需要应用鉴权的 OpenAPI 接口时作为凭证传入(如获取用户手机号接口)。clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******
expires_ininteger是token 有效期,单位为秒。过期后需要重新调用本接口获取新的 token。7200
captchastring否验证码信息,特殊场景下返回。-
desc_urlstring否描述链接,特殊场景下返回。-
descriptionstring否附加描述信息。-

响应示例

正常示例

{
    "code": 0,
    "msg": "success",
    "log_id": "20260309120000ABCDEF123456",
    "data": {
        "access_token": "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******",
        "expires_in": 7200,
        "captcha": "",
        "desc_url": "",
        "description": ""
    }
}

异常示例

{
    "code": 40001,
    "msg": "param error: invalid app_id",
    "log_id": "20260309120001ABCDEF654321",
    "data": null
}

错误码

HTTP 状态码错误码描述排查建议
2000请求成功-
20040001参数错误请检查请求参数是否完整、格式是否正确,确认 app_id、app_secret、grant_type 均已正确填写。
20040002app_id 无效请确认 app_id 是否正确,应用是否已在豆包应用插件开放平台正常创建并启用。
20040003app_secret 错误请确认 app_secret 是否与 app_id 匹配,可在应用详情页重新获取。
20042001访问频率超限请降低接口调用频率,建议缓存 access_token 并在过期前复用。

通过 login_code 获取用户 OpenID

使用端侧取得的一次性 login_code,换取当前用户在当前应用下的唯一标识 open_id。业务服务端应使用 app_id + open_id 关联自有账号;完整登录和账号绑定流程参见 登录接入(服务端)。

使用限制

  • login_code 为短期有效的一次性授权码,使用后即失效,不可重复使用。
  • 每个 login_code 仅能换取一次 open_id。

接口说明

  • 业务场景:用户在三方豆包应用插件中触发登录操作,豆包应用插件调用豆包登录组件获取 login_code,随后将其发送至三方服务端。服务端调用本接口将 login_code 换取用户在该应用下的唯一标识 open_id,用于关联三方自有账号体系。

  • 前提条件:

    • 已在豆包应用插件开放平台完成应用创建,获取到 app_id 和 app_secret。
    • 豆包应用插件客户端已完成用户登录授权流程,获取到有效的 login_code。
  • 注意事项:

    • login_code 有效期极短,服务端收到后应立即调用本接口,避免 code 过期。
    • open_id 是用户在当前应用下的唯一标识,同一用户在不同应用下的 open_id 不同。
    • 本接口使用 app_id + app_secret 进行鉴权,无需额外传入 access_token。

基本信息

名称描述
HTTP Path/api/login/v1/developer/get_openid
HTTP MethodPOST
Scope无需特殊 Scope
权限要求需要用户在豆包应用插件完成登录授权

请求头

名称类型必填描述
content-typestring是固定值 "application/json"

请求参数

Body

名称类型是否必填描述示例值
app_idstring是应用 ID,唯一标识一个三方应用。在豆包应用插件开放平台创建应用后获取。tt07e3715e218c94OR
app_secretstring是应用密钥,与 app_id 配对使用,用于验证应用身份。clt.943da17996fb5ceb******
grant_typestring是授权认证类型,固定值为 authorization_code 。authorization_code
login_codestring是短期登录 Code 授权码。用户在豆包应用插件完成登录授权后,客户端获取到的一次性短期有效授权码。0a1b2c3d4e5f******

请求示例

cURL:

curl -X POST 'https://hello.doubao-dev.com/api/login/v1/developer/get_openid' \
  -H 'content-type: application/json' \
  -d '{
    "app_id": "tt07e3715e218c94OR",
    "app_secret": "your_app_secret",
    "grant_type": "authorization_code",
    "login_code": "0a1b2c3d4e5f******"
  }'

Go:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://hello.doubao-dev.com/api/login/v1/developer/get_openid"
    requestBody := map[string]string{
        "app_id":     "tt07e3715e218c94OR",
        "app_secret": "your_app_secret",
        "grant_type": "authorization_code",
        "login_code": "0a1b2c3d4e5f******",
    }
    jsonData, _ := json.Marshal(requestBody)
    resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Java:

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GetOpenID {
    public static void main(String[] args) throws Exception {
        String url = "https://hello.doubao-dev.com/api/login/v1/developer/get_openid";
        String requestBody = """
            {
                "app_id": "tt07e3715e218c94OR",
                "app_secret": "your_app_secret",
                "grant_type": "authorization_code",
                "login_code": "0a1b2c3d4e5f******"
            }
            """;
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("content-type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Node.Js:

const axios = require('axios');

async function getOpenID() {
    const url = 'https://hello.doubao-dev.com/api/login/v1/developer/get_openid';
    const data = {
        app_id: 'tt07e3715e218c94OR',
        app_secret: 'your_app_secret',
        grant_type: 'authorization_code',
        login_code: '0a1b2c3d4e5f******'
    };
    try {
        const response = await axios.post(url, data, {
            headers: { 'content-type': 'application/json' }
        });
        console.log(response.data);
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}
getOpenID();

响应参数

名称类型是否必填描述示例值
codeinteger是响应状态码,0 表示成功,非 0 表示失败。0
msgstring是响应状态描述信息。success
log_idstring是日志 ID,用于问题排查时提供给技术支持。20260309120000OPENID789012
dataobject是响应数据对象,详见下方 data 字段说明。-

data 字段说明

名称类型是否必填描述示例值
open_idstring是用户在当前应用下的唯一标识 OpenID。同一用户在不同应用下的 open_id 不同,可用于三方自有账号体系的绑定或注册。_000Hkg5Wu1LTSk61Rsv5Y7lsfMD******

响应示例

正常示例

{
    "code": 0,
    "msg": "success",
    "log_id": "20260309120000OPENID789012",
    "data": {
        "open_id": "_000Hkg5Wu1LTSk61Rsv5Y7lsfMD******"
    }
}

异常示例

{
    "code": 40004,
    "msg": "login_code is invalid or expired",
    "log_id": "20260309120001OPENID345678",
    "data": null
}

错误码

HTTP 状态码错误码描述排查建议
2000请求成功-
20040001参数错误请检查请求参数是否完整、格式是否正确,确认 app_id、app_secret、grant_type、login_code 均已正确填写。
20040002app_id 无效请确认 app_id 是否正确,应用是否已在豆包应用插件开放平台正常创建并启用。
20040003app_secret 错误请确认 app_secret 是否与 app_id 匹配,可在应用详情页重新获取。
20040004login_code 无效或已过期login_code 为一次性短期有效授权码,请确认 code 是否已被使用或已过期,需重新引导用户授权获取新的 login_code。
20040005grant_type 不正确请确认 grant_type 的值为 authorization_code 。

通过 phone_code 获取用户加密手机号

使用端侧取得的一次性 phone_code 换取用户的加密手机号。调用前,业务服务端需要先获取应用级 access_token,并通过请求头 x-DB-AccessToken 传入;接口返回的是密文,不会直接返回明文手机号。

使用限制

  • phone_code 为一次性授权码,短期有效,使用后即失效,不可重复使用。
  • 本接口需要传入应用级 access_token(通过「获取应用级别鉴权 Token」接口获取),请确保 token 未过期。
  • 接口返回 encrypt_phone_number 密文,业务服务端使用与平台登记的开发者证书配套的私钥解密。证书准备、数据方向和解密方法参见 关于证书。

接口说明

  • 业务场景:用户在三方豆包应用插件中授权手机号,豆包应用插件调用豆包获取手机号组件获得 phone_code,发送至三方服务端。服务端调用本接口获取用户加密手机号,解密后可用于账号绑定或注册。

  • 前提条件:

    • 已通过「获取应用级别鉴权 Token」接口获取有效的 access_token。
    • 豆包应用插件客户端已完成用户手机号授权流程,获取到有效的 phone_code。
  • 注意事项:

    • phone_code 有效期极短,服务端收到后应立即调用本接口,避免 code 过期。
    • 解密必须在业务服务端完成,禁止将开发者私钥或解密后的明文手机号下发到应用插件。
    • 手机号属于用户敏感信息,解密后请遵守相关隐私法规妥善处理。

基本信息

名称描述
HTTP Path/api/login/v1/developer/get_user_phonenumber
HTTP MethodPOST
Scope无需特殊 Scope
权限要求需要用户在豆包应用插件完成手机号授权

请求头

名称类型必填描述
content-typestring是固定值 "application/json"
x-DB-AccessTokenstring是应用级 token,通过「获取应用级别鉴权 Token」接口获取。示例:clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******

请求参数

Body

名称类型是否必填描述示例值
phone_codestring是一次性获取手机号授权码。用户在豆包应用插件授权手机号后,客户端获取到的短期有效一次性授权码。9f8e7d6c5b4a******

请求示例

cURL:

curl -X POST 'https://hello.doubao-dev.com/api/login/v1/developer/get_user_phonenumber' \
  -H 'content-type: application/json' \
  -H 'x-DB-AccessToken: clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******' \
  -d '{
    "phone_code": "9f8e7d6c5b4a******"
  }'

Go:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://hello.doubao-dev.com/api/login/v1/developer/get_user_phonenumber"
    requestBody := map[string]string{
        "phone_code": "9f8e7d6c5b4a******",
    }
    jsonData, _ := json.Marshal(requestBody)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("content-type", "application/json")
    req.Header.Set("x-DB-AccessToken", "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Java:

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GetUserPhoneNumber {
    public static void main(String[] args) throws Exception {
        String url = "https://hello.doubao-dev.com/api/login/v1/developer/get_user_phonenumber";
        String accessToken = "clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******";
        String requestBody = """
            {
                "phone_code": "9f8e7d6c5b4a******"
            }
            """;
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("content-type", "application/json")
                .header("x-DB-AccessToken", accessToken)
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Node.Js:

const axios = require('axios');

async function getUserPhoneNumber() {
    const url = 'https://hello.doubao-dev.com/api/login/v1/developer/get_user_phonenumber';
    const accessToken = 'clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqn******';
    const data = {
        phone_code: '9f8e7d6c5b4a******'
    };
    try {
        const response = await axios.post(url, data, {
            headers: {
                'content-type': 'application/json',
                'x-DB-AccessToken': accessToken
            }
        });
        console.log(response.data);
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
    }
}
getUserPhoneNumber();

响应参数

名称类型是否必填描述示例值
codeinteger是响应状态码,0 表示成功,非 0 表示失败。0
msgstring是响应状态描述信息。success
log_idstring是日志 ID,用于问题排查时提供给技术支持。20260309120000PHONE345678
dataobject是响应数据对象,详见下方 data 字段说明。-

data 字段说明

名称类型是否必填描述示例值
encrypt_phone_numberstring是加密后的手机号。三方服务端需使用平台约定的密钥和解密算法进行解密后获取明文手机号。解密方法参见 8.1 关于证书U2FsdGVkX1+Z7e5k******

响应示例

正常示例

{
    "code": 0,
    "msg": "success",
    "log_id": "20260309120000PHONE345678",
    "data": {
        "encrypt_phone_number": "U2FsdGVkX1+Z7e5k******"
    }
}

异常示例

{
    "code": 40006,
    "msg": "phone_code is invalid or expired",
    "log_id": "20260309120001PHONE901234",
    "data": null
}

错误码

HTTP 状态码错误码描述排查建议
2000请求成功-
20040001参数错误请检查请求参数是否完整、格式是否正确,确认 phone_code 已正确填写。
20040006phone_code 无效或已过期phone_code 为一次性短期有效授权码,请确认 code 是否已被使用或已过期,需重新引导用户授权获取新的 phone_code。
20041001access_token 无效或已过期请确认请求头中的 x-DB-AccessToken 是否正确传入,token 是否已过期。如已过期,请重新调用「获取应用级别鉴权 Token」接口获取新的 token。
20041002access_token 缺失请在请求头中添加 x-DB-AccessToken 字段并传入有效的应用级 token。