Third-Party App
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
| Capability Domain | Description |
|---|---|
| Local Assistant Chat | Message interaction with the PC local assistant via API |
| Cloud Task Management | Create and manage cloud AI tasks; supports mobile / app sessions |
| Artifact Management | Fetch session artifacts, incremental updates, and media file downloads |
| Redemption Code Redemption | Redeem WorkBuddy credits for users via vouchers or redemption codes |
Terminology
| Role | Description | Trust Boundary |
|---|---|---|
| Resource Owner | The resource owner, typically a WorkBuddy user | Determines the resource scope accessible to third-party apps or connectors |
| Third Application | A standard third-party application built on WorkBuddy Open Platform | Can call Open API after user authorization |
| WorkBuddy | The agent runtime that executes tasks and initiates tool calls on behalf of the user | Short-lived credentials should be obtained before calling |
| Open Platform | The open platform responsible for app registration, authorization confirmation, token issuance, Scope management, and auditing | Platform-level trust boundary; the permission source for all open API calls |
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:
- First, the third-party application initiates user authorization
- After the user completes authorization, the application server exchanges for access credentials
- 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 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
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
- Sign in to WorkBuddy Open Platform
- Click "Hardware Access"
- Fill in the basic information
- Configure permission management information
- Configure the OAuth callback URL
- Submit for review
Credential notes: After creation, the application enters draft 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.
Application Status
| Status | Description |
|---|---|
| Under Review | Application configuration submitted; awaiting platform review |
| Enabled | Application approved and published; can call authorized Open APIs |
| Rejected | Application review failed; modify the configuration based on review feedback and resubmit |
Authorization-related API documentation is collected in "Open API Reference".
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
| Token Type | Purpose | Validity | Notes |
|---|---|---|---|
| access_token | Credential for calling Open API | 24 hours | Obtained via "Exchange for Access Credentials"; must be re-obtained after expiration. |
| refresh_token | Refresh access_token | 60 days | Obtained via "Exchange for Access Credentials"; must be stored securely on the server and must not be exposed in frontend or client code. |
Permission Configuration List and Related APIs
Scope Permission List
| Category | Scope | Permission Name | Description |
|---|---|---|---|
| User profile | user.profile.readable | Read personal profile | Read the user's nickname and avatar |
| User profile | user.contact.readable | Verify contact information | Check whether the phone number provided by the caller matches the user's phone number |
| Credits and benefits | user.credit.exchange | Redeem credits via voucher | Redeem WorkBuddy credits for the user via a voucher or redemption code |
| Cloud tasks | user.task.invokable | Create and execute cloud tasks | Allow the application to create and execute cloud tasks per user instructions |
| Cloud tasks | user.task.readable | Read task list and details | Allow the application to read the user's cloud task list and task details |
| Local assistant | user.localassistant.invokable | Send messages to the local assistant | Send messages to the local assistant (the user's PC) to drive the on-device Agent to execute tasks |
| Local assistant | user.localassistant.readable | Read local assistant online status and message history | Read the local assistant's (user PC) online status and conversation message history |
Permission Application Guide
Application Steps
- On the application management page, select the Scope to apply for
- Describe the use case and necessity
- 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.