Introduction
The Workbench Open Platform connects enterprise business systems to the Workbench. An app can provide business functions through a web entry point for employees, read organization data within its authorized scope through Server APIs, send robot messages, and receive organization-change events.
Platform overview
The Workbench Open Platform brings together enterprise app entry points, identity, organization data, and messaging capabilities in one set of developer APIs. Developers only need to focus on app configuration, page integration, server-side calls, and business security; the platform's internal implementation does not need to be exposed to them.
Platform roles
| Role | Main responsibilities |
|---|---|
| Enterprise administrator | Manage apps, visibility scope, permissions, robots, and publication status |
| App owner | Maintain app configuration, entry URLs, and version releases |
| App frontend | Render pages, detect the runtime environment, and request a one-time authorization code |
| App backend | Store secrets, exchange tokens and user identity, and call Server APIs |
| Enterprise employee | Open apps in the Workbench and use their business functions |
App forms
- Web app: Configure desktop and mobile entry points and open the business page in the Workbench.
- Application robot: Send one-to-one messages to members as the app, suitable for alerts, notifications, and to-do reminders.
- Group robot: Bind a robot to a specific group and send messages through a Webhook.
- Event receiver: Receive organization-data change callbacks and perform signature verification, decryption, and idempotent processing on the app side.
Capabilities
| Capability | Typical use | Main documentation |
|---|---|---|
| Workbench app | Create an app, configure its entry point, set its visibility scope, and publish it | App creation and release on this page |
| In-container passwordless sign-in | The page obtains a one-time code through the SDK and the server exchanges it for the current user's identity | Client SDK, Passwordless sign-in |
| App-level API | The server uses access_token to call contact, enterprise information, and robot APIs | API overview on this page, Server API |
| Event subscription | The platform calls the app when organization data changes | Event subscription |
API overview
Server APIs use https://{gateway_host} as the common entry point. Except for OAuth APIs, most endpoints return the unified envelope { "code": 200, "msg": "", "data": {} }.
| Category | API or capability | Authentication | Description |
|---|---|---|---|
| Authentication | /auth/v1/oauth/token | appId + appSecret | Obtain an app-level access_token |
| Passwordless sign-in | SDK obtains code, /auth/v1/oauth/userinfo | Client session + app token | Obtain the current user's identity |
| Contacts | /open/v1/contact/* | access_token | Query departments and members |
| Enterprise information | /open/v1/enterprise/info | access_token | Query the enterprise name and logo |
| Application robot | /open/v1/robot/messages | access_token | Send one-to-one or batch robot messages |
| Group robot | /webhook/robot/send | Webhook token + signature | Send messages to a specific group |
| Event subscription | HTTPS callback URL configured for the app | Platform signature and encryption | Receive organization changes |
Permission scopes
| Permission scope | Purpose |
|---|---|
link.snsapi.base | Request an in-container passwordless sign-in code |
contact.department.read | Read departments and department members |
contact.user.read | Read member details |
enterprise.info.read | Read basic enterprise information |
robot.push | Send application robot messages |
Common conventions
- App-level tokens are valid for 7200 seconds by default. Cache them and refresh them before expiry.
codeis valid for 300 seconds by default and can be used only once.- Member IDs and department IDs are strings in JSON.
- Query APIs may be retried a limited number of times after network errors or 5xx responses; do not automatically retry authentication, parameter, or permission errors.
- See Server API for detailed parameters, response fields, and multilingual examples.
Core concepts and credentials
App status
| Status | Description |
|---|---|
| In development | The app can be configured and tested but is not available to employees |
| Published | The app is distributed to the Workbench according to its visibility scope and its open APIs are available |
| Disabled | Employees cannot open the app and issued tokens are invalid |
| Deleted | The app and its configuration are deleted, and the original app identifier cannot be reused |
Key concepts
| Concept | Description |
|---|---|
| Visibility scope | Determines which employees can see the app and which organization data the contact APIs return |
| Platform entry point | The H5 URL used when the app opens on desktop or mobile |
| In-container sign-in URL | An allowlisted URL from which a page may request a code |
| Application robot | A robot that sends one-to-one messages to members as the app |
| Group robot | A robot bound to a group that sends messages through a Webhook |
| Event subscription | A mechanism through which the platform actively calls the app when organization data changes |
Credential responsibilities
| Credential | Used by | Purpose | Security requirement |
|---|---|---|---|
appId | Frontend and backend | Identify the app | May appear in the frontend, but cannot authenticate by itself |
appSecret | Backend | Obtain the app access_token | Store only on the backend |
access_token | Backend | Call open APIs | Never send it to a browser or client |
code | Frontend to backend | Exchange once for the current user's identity | Do not cache, log, or put it in a URL |
| Webhook token and secret | Backend | Call the group robot | Store only on the server and rotate regularly |
The client session is used only to request a code; the app access_token is used only for server-side open API calls. Do not mix the client session, app token, or app secret.
Exchanging identity
- The page requests a one-time
codethrough the official SDK. - The page submits the
codeto the app backend over HTTPS. - The app backend uses
access_tokento call the UserInfo API. - The backend creates its own app session based on the returned
userId.
The identity bound to the code is authoritative. A user ID supplied separately in the request body cannot override the platform identity.
App creation and release
Create an app
Open the Developer Center in the admin console and create an enterprise internal app. Enter the app name, icon, owner, and description. After creation, the platform provides an appId; appSecret is shown only to authorized administrators and should be saved immediately in the server-side secret manager.
Configure the app
| Configuration | Purpose |
|---|---|
| Desktop platform entry point | H5 URL employees open from the desktop Workbench |
| Mobile platform entry point | H5 URL employees open from the mobile Workbench |
| In-container sign-in URL | Allowlist of pages that may request a code |
| Visibility scope | Determines which employees can see the app and which organization data it can read |
| Open permissions | Enable Server API capabilities such as contacts, enterprise information, and robots |
| IP allowlist | Optionally restrict the source IPs allowed to call Server APIs |
| Event subscription | Configure the organization-event callback URL, signing token, and encryption key |
| Robots | Create an application robot or configure a group robot |
The platform entry point and the in-container sign-in URL are different settings: the entry point determines where the app opens, while the sign-in URL determines which pages can request authorization.
Publish a version
After saving the configuration, create and publish a version. Only a published, enabled app with client display enabled is distributed to the Workbench and can use the open APIs normally.
Before publishing, check the following:
- Both desktop and mobile entry points are reachable HTTPS URLs.
- The sign-in URL allowlist covers every page that requests authorization.
- The visibility scope and open permissions follow least privilege.
- The backend has configured
appSecret, callback verification, and token caching. - The page handles browser environments, authorization failures, network timeouts, and repeated entry.
- Robot messages have an idempotency key and a failure-retry policy.
Change a version
After changing entry points, visibility scope, permissions, or robot settings, publish a new version and verify it on the target clients. Disabling the app prevents employees from opening it and invalidates issued access_token values; after deletion, the original appId cannot be reused.
Robots and events overview
The platform provides two robot capabilities and one event-subscription capability. Their credentials, message scopes, and processing requirements are different.
| Capability | Purpose | Call or receive method | Suitable scenarios |
|---|---|---|---|
| Application robot | Send one-to-one messages to members as the app | Server API + access_token | Alerts, to-dos, and approval reminders |
| Group robot | Send messages to a bound group | Webhook + signature | Group notifications and duty broadcasts |
| Event subscription | Receive member and department changes | HTTPS callback + verification and decryption | Incremental organization-data synchronization |
Selection guidance
- Use an application robot to reach specific members. For batch sends, use the batch API and process item-level results.
- Use a group robot when you only need to broadcast to one work group. Do not treat a Webhook secret as an app token.
- Use event subscriptions as change signals for continuous organization synchronization, and periodically reconcile with the contact APIs.
General security requirements
- Store all robot and event secrets only on the server.
- Use idempotency keys for sends and deduplicate events by
eventId. - Verify the signature, timestamp, and decryption result before parsing callback business fields.
- Do not record tokens, signature input, authorization codes, or complete callback ciphertext in logs.
Minimum integration flow
Create an app → configure entry points and permissions → publish the app → request code
→ exchange the user identity on the server → call business APIs → establish the app's own session
Design principles
- Clients and servers use different credentials; neither can replace the other.
- The app visibility scope affects Workbench display, passwordless sign-in, and contact data returned by the APIs.
- A one-time
codeis only used to exchange the user's identity; after the exchange, the app should establish its own sign-in state. - Robot messages and event subscriptions should both define idempotency, retry, and failure-alerting strategies.