Third-Party App

Hardware Access and Credits Redemption

Integration Introduction

Platform Overview

WorkBuddy Open Platform uses the OAuth 2.1 specification for user authentication and authorization, and provides HTTPS-based Open APIs for developers and ecosystem partners. Third-party applications can operate on user data through the Open API after obtaining user authorization.

To protect the security and privacy of user data, third-party applications must explicitly request authorization from the user before accessing user data. After the user authorizes, the platform issues third-party credentials in accordance with the OAuth specification. Third-party applications can obtain these credentials and perform the required operations with the platform.

Core Capabilities

Application Types

The Open Platform currently supports three types of third-party applications for different integration scenarios:

Terminology

Integration Guide

Integration Flow Overview

Step 1: Create an Application and Complete Configuration

In WorkBuddy Open Platform, fill in the application basic information, permission management information, and callback URL configuration in one pass. After completing all application configuration, submit for review.

Step 2: From User Authorization to Calling APIs

The application guides the user through OAuth 2.1 authorization. After the server exchanges for access credentials, it can call the Open API. The overall process consists of three consecutive stages:

1. First, the third-party application initiates user authorization

2. After the user completes authorization, the application server exchanges for access credentials 3. The application uses the access credentials to call the required Open API

For details on authorization requests, see "Auth API: Request User Authorization". For obtaining and refreshing access credentials, see "Auth API: Exchange for API Access Credentials". For parameters, permissions, and response structures of specific business APIs, see "Open API Reference". The following sequence diagram shows the complete process from user authorization to API calls.

Application Registration and Authorization

Hardware Access

Hardware Access is open to hardware device vendors and partners. After creating a hardware access application on the Open Platform, hardware devices (such as smart glasses and in-vehicle systems) can complete OAuth 2.1 authorization with the user and then use Open APIs for local assistant chat, cloud task management, session artifacts, and more, extending WorkBuddy's agent capabilities to hardware terminals.

When creating a hardware access application, complete the basic information, permission management information, and callback URL configuration in one pass. After submission, the application enters the review process. Once approved, the application is published and the corresponding capabilities are enabled.

Application Basic Configuration

1. Sign in to WorkBuddy Open Platform
2. Click "Hardware Access"
3. Fill in the basic information
4. Configure permission management information
5. Configure the OAuth callback URL
6. Submit for review

Credits App

The Credits App is open to developers and partners for credit-benefits redemption. After user authorization, the application can use Open APIs to redeem WorkBuddy credits for users via vouchers or redemption codes, suitable for credit issuance and similar scenarios.

When creating a credits app, complete the basic information, permission management information, and callback URL configuration in one pass. After submission, the application enters the review process. Once approved, the application is published and the corresponding capabilities are enabled.

Application Basic Configuration

1. Sign in to WorkBuddy Open Platform
2. Click "Other > Credits"
3. Fill in the basic information
4. Configure permission management information (only credits and benefits Scopes are available)
5. Configure the OAuth callback URL
6. Submit for review

Application Notes

Application credential notes: After creation, the application enters review status and the platform generates client_id and client_secret. client_secret is shown in plaintext only once after the application is created successfully. Keep client_secret secure and do not expose it in frontend or client code. If it is lost, contact the platform.

Authorization

After the application is approved and enabled, guide the user through OAuth 2.1 authorization to obtain an access_token. The authorization flow involves two types of endpoints. Full API documentation is in "Open API Reference":

• "Auth API" — GET /authorize (request user authorization), POST /token (exchange / refresh Token)

Token Types Overview

Permission Configuration List and Related APIs

Scope Permission List

Permission Application Guide

Application Steps

1. On the application management page, select the Scope to apply for
2. Describe the use case and necessity
3. Submit for review

Principle of least privilege: Apply only for Scopes required by the application's features; when the user authorizes, request only the Scopes needed for the current operation; avoid requesting permissions beyond business needs.

Share Capability Integration

Feature Overview

WorkBuddy Share lets a third-party application send text, images, audio, files, and resource links into WorkBuddy in one step.

WorkBuddy Share is open to developers who have completed enterprise verification. Create a share application on WorkBuddy Open Platform (fill in Basic configuration → App platform information), submit it for review, and an application ID is generated. After approval, generate a key pair to obtain share integration permission.

WorkBuddy Share currently supports PC integration (Windows applications / macOS applications). Mobile integration (Android / iPhone / HarmonyOS applications) will be available later.

Before You Integrate

Before integrating the share capability, create a share application on WorkBuddy Open Platform, pass review, and generate a key pair. Confirm that the user's WorkBuddy client is 5.8.0 or later. Earlier versions cannot launch a share. Mobile integration (Android / iPhone / HarmonyOS) and the share SDK will be available later.

On the Open Platform, open Third-party integration → Share capability integration, click Create application, and complete the two steps Basic configuration → App platform information. You can Save draft at any time. An application ID is generated as soon as you submit for review, and the review finishes within 7 business days. After approval, generate a key pair on the application details page, then integrate by following the PC Development Guide.

Step 1: Basic Configuration

Step 2: App Platform Information

Select the platforms to integrate (Windows application / macOS application). Select at least one. Each selected platform expands into its own card.

Windows application

Read the subject and thumbprint together (PowerShell; replace the path with your exe path):

$sig = Get-AuthenticodeSignature "C:\Path\To\App.exe"
$sig.SignerCertificate.Subject      # 例：CN="XXX Technology Co., Ltd.", O="XXX Technology Co., Ltd.", C=CN
$sig.SignerCertificate.Thumbprint   # 例：A1B2C3D4E5F6…（40 位十六进制）

The application must be published with a code signing certificate (OV / EV certificates require a verified company application). Self-signed or unsigned applications cannot pass review.

macOS application

Read the Bundle ID and Team ID together (Terminal; replace the path with your .app path):

defaults read /Applications/你的应用.app/Contents/Info.plist CFBundleIdentifier        # 例：com.example.app
codesign -dv --verbose=4 /Applications/你的应用.app 2>&1 | grep TeamIdentifier          # 例：TeamIdentifier=AB12CD34EF

The Team ID comes from the Apple Developer Program membership page and is shared by every application in the same team. If you cannot see it, confirm that the account has joined the developer program.

What these fields are for: Launching on desktop does not verify the caller's application signature. The Windows code signing subject and thumbprint, and the macOS Team ID, are used for registration, uniqueness checks, and review. A wrong value does not block launch, but it is rejected during review.

Submission and Review

After both steps are complete, click Submit for review.

Generate a Key Pair

The key pair is generated after the application is approved. It is not submitted when the application is created.

Identifier Conflicts and Appeals

To appeal: if the identifier or name is yours (for example after a rebind, or when another account claimed it by mistake), email openworkbuddy@tencent.com. Include the occupied application name or identifier, your developer organization name, and proof of ownership (a software copyright certificate, screenshots of a store console, and similar). The platform checks the verified organization and then updates ownership.

Using the WorkBuddy Brand Mark

After you integrate the share capability, show the WorkBuddy mark on the entry in your application that launches a share (the share target in the share panel, and the integration badge on the settings page), so users can see where the content will go. The mark must follow the WorkBuddy brand guidelines: WorkBuddy Brand Center (switch to the WorkBuddy brand after you open it, and download logo assets from 徽标 on that page).

The platform checks mark usage during application review and in production. If the mark is not used as specified, the platform may require a correction and pause the share capability.

FAQ

After the steps above, integrate the share capability by following the PC Development Guide.

PC Development Guide

Supported versions: WorkBuddy 5.8.0 and later.

Capability Overview

A third-party application builds a share message, signs a packet with the application private key, and hands it to WorkBuddy through the PC HTTPS interstitial page or, later, the mobile SDK. After WorkBuddy validates the request, it prefills the content into the task input. The user can review, edit, and send. A successful launch or a successful prefill does not mean the user has submitted the task.

The current share scene value is always newTask. If the new-task input in WorkBuddy already has content, the shared content overwrites that input. Otherwise a new task is created and the content is filled into the task input. newTask is the name of a protocol scene. It does not mean every share is forced to create a brand-new task.

The message payload uses TaskPayload. Its content blocks can carry text, images, audio, file resources, and resource links. Support for local resources and embedded data differs by platform. See below.

Quick Start: Share a Text Message

The example below uses Node.js built-in modules. It signs on the server and produces the PC HTTPS interstitial link. You first need a real appId, kid, and the matching private key from the Open Platform. Save the private key as private-key.pem on the server, keeping the PEM header, footer, and line breaks. Do not commit this file to a repository.

Save the following code as sign.cjs:

const fs = require('node:fs');
const crypto = require('node:crypto');
const b64 = value => Buffer.from(value, 'utf8').toString('base64');
const appId = process.env.APP_ID;
const kid = process.env.KEY_ID;
if (!appId || !kid) throw new Error('缺少 APP_ID 或 KEY_ID');
const messageObject = {
  title: '分析仓库',
  description: '请总结仓库结构',
  payload: {
    action: 'start',
    promptContentBlocks: [{ type: 'text', text: '分析这个仓库' }]
  }
};
const messageJson = JSON.stringify(messageObject);
if (Buffer.byteLength(messageJson, 'utf8') > 16384) {
  throw new Error('原始消息 JSON 超过 16 KiB');
}
const packet = {
  appId,
  kid,
  message: b64(messageJson),
  nonce: crypto.randomBytes(16).toString('hex'),
  scene: 'newTask',
  timestamp: String(Math.floor(Date.now() / 1000))
};
const signingText = [
  `appId=${b64(packet.appId)}`,
  `kid=${b64(packet.kid)}`,
  `message=${packet.message}`,
  `nonce=${b64(packet.nonce)}`,
  `scene=${b64(packet.scene)}`,
  `timestamp=${b64(packet.timestamp)}`
].join('&');
packet.sig = crypto.sign('sha256', Buffer.from(signingText, 'utf8'), {
  key: fs.readFileSync('./private-key.pem', 'utf8'),
  padding: crypto.constants.RSA_PKCS1_PADDING
}).toString('base64');
const query = new URLSearchParams(packet).toString();
console.log(`https://workbuddy.cn/app/open-deeplink?${query}`);

Run it in the server directory where the private key is stored (replace the values with your application):

APP_ID='你的应用标识' KEY_ID='对应的密钥标识' node sign.cjs

Open the HTTPS interstitial link that is printed, and confirm that it launches WorkBuddy, prefills the message in the input, and then lets the user edit and send. Generate the signed packet when the user starts a share. Do not generate a link ahead of time and reuse it for a long time.

The Full PC Link

The PC side exposes an HTTPS interstitial page: https://workbuddy.cn/app/open-deeplink. The third-party application opens the link, with its parameters, in the system browser. After the user confirms, WorkBuddy is launched. If the client is not installed, the page can guide the user to install it.

The link uses seven query parameters: appId, kid, message, nonce, scene, timestamp, and sig. Encode the transport parameters with URLSearchParams. Do not concatenate the Base64 characters +, /, and = by hand.

The link below is a complete example of every field and value. It was produced with a temporary RSA-2048 key and verified locally, but app_demo and kid_demo are not registered on the platform, and the example timestamp expires. It cannot be used for a real share.

HTTPS interstitial page:

https://workbuddy.cn/app/open-deeplink?appId=app_demo&kid=kid_demo&message=eyJ0aXRsZSI6IkRlbW8iLCJkZXNjcmlwdGlvbiI6IkRlbW8iLCJwYXlsb2FkIjp7ImFjdGlvbiI6InN0YXJ0IiwicHJvbXB0Q29udGVudEJsb2NrcyI6W3sidHlwZSI6InRleHQiLCJ0ZXh0IjoiSGVsbG8gV29ya0J1ZGR5In1dfX0%3D&nonce=9f2c8b1a6d4e7035c8a912f0b7d6e453&scene=newTask&timestamp=1791515336&sig=s%2Bbo02%2BkPMj%2BbJV9iuzAxsIo3oEoPVYLl%2FkgPqQe4J0MTEEqa2kxmSssB%2Bg%2BzhsD1UZrNTlMPLQfUbApszCx05ujCKJ%2Fmn5u3QdoiWsIwl7dejptqHLI9iLIndlVroeliQ7r1mKtZNjLElWH4GNCeQbA2taPZanBcrcTQ5LXPXRRouxmryDPq%2FgbFKH9%2FU5vAoZUFEnKI1NqMs1W2QkEvLhj6kDOz2NmffZK64mHrpMlip6v3hD3ImPECWen1xmJJhetTV4Iy8bsinsio3PG7ccNf9dqYtpevWPlQlQhl09GVvhfNrKjQREkJG5Y6SkA3pIoB8vbNdLSH09D1UgV2Q%3D%3D

URL-decode message above, then decode it as standard Base64. The UTF-8 JSON is:

{"title":"Demo","description":"Demo","payload":{"action":"start","promptContentBlocks":[{"type":"text","text":"Hello WorkBuddy"}]}}

%3D, %2B, and %2F are the URL encodings of the Base64 characters =, +, and /. The values used for signing are the field values before URL encoding. The values used in the link are the transport values after signing is complete.

Parameter Types and Message Structure

Transport Signature Packet

The table describes the transport values in the URL query parameters or the signature packet. message is a string in transit. It becomes a WorkBuddyMessage object only after decoding. The actual parameters of the mobile SDK follow its official API documentation.

The first six fields are signed. Together with sig there are seven fields. Do not send the public key used for verification.

WorkBuddyMessage

Serialize the whole message object first, then count the bytes of the raw UTF-8 JSON. The 16 KiB limit applies to the raw JSON, not to the URL length and not to the length of the Base64 string. If you embed media in data, those characters count toward the JSON byte size as well.

TaskPayload

The specified connectors should already be published, and they should belong to the same organization as the share application. Whether the user has authorized still affects whether the resource can be read.

ContentBlock Types

A ? in the table only means a given source might omit that field. It is not a promise about field combinations or which fields are required. Whether WorkBuddy can read a resource path or link depends on what the target platform can access. A local file:// path that the third-party application can read is not necessarily readable by WorkBuddy. _meta may include preview fields such as og:title, og:image, and og:description. Field combinations, size limits, and the full per-platform support matrix follow the official SDK and protocol.

Text block example:

{"type":"text","text":"分析这个仓库"}

Resource link block example:

{"type":"resource_link","name":"产品文档","uri":"https://example.com/docs","_meta":{"og:title":"产品文档"}}

Signature Generation: Detailed Steps

The signature algorithm is RS256: RSA PKCS#1 v1.5 padding and a SHA-256 digest. Sign with the RSA-2048 private key (PKCS#8 PEM) paired with kid. Keep and use the private key on the developer's server.

1. Build the message object. Fill in title, description, and TaskPayload. For example, the text message in Quick Start.
2. Serialize the JSON. JSON-serialize the whole message object and take the exact UTF-8 byte sequence. The raw JSON must not exceed 16,384 bytes. Do not serialize or modify the message again between signing and sending, or the bytes may change.
3. Produce message. Apply one standard Base64 encoding to the UTF-8 bytes from step 2. Keep +, /, and any required = padding. Use that value as-is when signing. Do not Base64-encode message a second time.
4. Prepare the other fields. Read appId and kid, and set scene to newTask. Use a cryptographically secure random generator to produce 16 bytes, and convert them to a 32-character lowercase hexadecimal nonce. Produce the Unix-seconds string timestamp for this request.
5. Encode the plain field values separately. Apply standard Base64 to the UTF-8 bytes of each of appId, kid, nonce, scene, and timestamp. Encode only the values. Do not encode =, &, or the parameter names.
6. Build the signing string. Join the fields in ASCII order of the key names, appId → kid → message → nonce → scene → timestamp. Parameter names are case-sensitive. Put a single & between items, and do not add a trailing space or newline:

appId=Base64(appId)&kid=Base64(kid)&message=message&nonce=Base64(nonce)&scene=Base64(scene)&timestamp=Base64(timestamp)

7. Produce sig. RS256-sign the UTF-8 bytes of the signing string from step 6, then apply standard Base64 to the signature bytes. sig is not included in the signing string it belongs to.
8. Build the transport link. Pass the six raw transport field values and sig to URLSearchParams as seven query parameters. The URL carries the raw values such as appId and kid, not the Base64(appId) and Base64(kid) used inside the signing string.
9. Check validity and retries. Require -30 ≤ platform current time − timestamp ≤ 300, in seconds. A retry of the same share keeps the original packet. After a new share, or after the packet expires, generate nonce, timestamp, and sig again. The same appId + nonce may pass in-app verification at most 3 times.

When a signature fails, first compare the exact signing string both sides used: field order, case, Base64 padding, whether message was encoded twice, and whether a newline was mixed in. Then check that kid matches the private key. Do not put the private key, or a complete real share link, into a support ticket.

Sharing Resources and Connectors

Before sharing an image, audio, a file, or a link, confirm that the target platform supports that content form, and that WorkBuddy can read the referenced resource. Remote resource links should stay valid. A local file URI works only when the target platform can access it. On PC, do not rely on embedding an image, audio, or file directly in the message through data.

When a connector is required, put the connectors published under the application's organization in TaskPayload.connectorIds. If the user has not authorized, the resource cannot be accessed, or the content does not pass review, the share may not be prefilled. Let the user adjust the content and share again.

Error Handling and Launch Checklist

Before launch, verify at least: a plain-text share through the PC HTTPS interstitial page, the client not installed, a wrong private key, an expired request, a repeated request, an identity mismatch, and an unreachable resource.