---
id: "en/developer-api-overview"
title: "Development API Overview"
language: "en"
description: "Introduces enterprise development accounts, authentication methods, API directories, calling specifications and developer indexes."
canonical_url: "https://www.babel.cc/public/babelwiki/en/developer-api-overview.html"
markdown_url: "https://www.babel.cc/public/babelwiki/ai/en/developer-api-overview.md"
alternates: {"en": "https://www.babel.cc/public/babelwiki/ai/en/developer-api-overview.md", "zh": "https://www.babel.cc/public/babelwiki/ai/zh/developer-api-overview.md"}
reading_note: "文档记录不等于当前部署能力；以实际版本、授权模块与配置为准。保留原文的可选、限制及待确认说明，勿补猜接口。 / Documentation is not a guarantee for every deployment. Preserve optional-module requirements, limitations and unresolved API contracts."
---

# Development API Overview

BabelBird develops APIs to connect the authentication, file, sharing, organization, messaging and login capabilities of enterprise network disks to third-party business systems. The left column is grouped by interface function, and the callable endpoints are listed directly in the group.

## Call overview

- The enterprise administrator creates a developer account in the private cloud enterprise management background and obtains `client_id`, `client_secret` and JWT related keys.
- In the OAuth callback method, use `/api/authorize.do` to obtain the authorization code, and then use `/api/token.do` to obtain `access_token`.
- JWT login-free method uses `/api/authorizeByJWT.do` or `/account/tokenLogin.do`, and private deployment needs to enable the corresponding configuration.
- File access API requests need to carry `Authorization: Bearer <access_token>` in the HTTP Header.
- POST, PUT, DELETE requests usually use `Content-Type: application/json`.

### JWT Claims and Validity {#jwt-contract-pending-confirmation}

Two purposes are confirmed: `/account/tokenLogin.do` establishes a web session using a `userToken` carrying the user's `email`, `phone` or `babelId`. It can open a specified file with `fileId` and show only the file list with `onlyFileList=1`. `/api/authorizeByJWT.do` uses a `jwt_token` carrying the developer's `client_id`, with the user specified in query parameters, to obtain a `code` for exchange through `/api/token.do` into access and refresh tokens. These JWTs are not interchangeable.

The following structure is confirmed for the current deployment: `time`, `duration` and `payload` are top-level claims. `time` is the Unix timestamp in milliseconds when the JWT is generated; `duration` is that JWT's lifetime in seconds; `payload` is the business object. Email-based web login uses `payload.email`. Developer authorization uses `payload.client_id`, which is numeric in the supplied sample.

Decoded web-login `userToken` (identity and timestamp are illustrative):

```json
{
  "duration": 60,
  "payload": {"email": "user@example.com"},
  "time": 1790000000000
}
```

Decoded authorization `jwt_token` (application ID and timestamp are illustrative):

```json
{
  "duration": 60,
  "payload": {"client_id": 1000000000001},
  "time": 1790000000000
}
```

`60` means these sample JWTs have a 60-second lifetime; it is not a confirmed fixed value or default. Generate `time` from the current clock for each JWT rather than copying the example timestamp. This lifetime applies to the JWT submitted to the login or authorization endpoint, not to the resulting web session or the exchanged `access_token`. Confirmation covers the current deployment, not all historical versions.

### Java JWT Integration Example

The following example is adapted from the BabelBird API integration sample. It demonstrates how to generate a JWT string. In a real project, replace the secret, enterprise domain, user email, phone number, employee ID and `client_id` with values provided by the enterprise admin console or implementation team. Do not expose the JWT secret in frontend pages, client packages or public repositories.

The JWT payload contains three core fields:

| Field | Description |
| --- | --- |
| `time` | Token generation timestamp in milliseconds |
| `duration` | Token validity duration in seconds |
| `payload` | Business object: the current email-login sample is `{"email":"user@example.com"}`; the developer-authorization sample is `{"client_id":1000000000001}`. |

Common usage:

- User login-free access: generate `userToken`, then open `/account/tokenLogin.do?userToken=<JWT_TOKEN>`.
- OAuth/JWT authorization: generate `jwt_token`, then open `/api/authorizeByJWT.do?response_type=code&client_id=<CLIENT_ID>&jwt_token=<JWT_TOKEN>&email=<USER_EMAIL>`, and exchange the returned `code` for `access_token`.
- File API calls: after obtaining `access_token`, include `Authorization: Bearer <access_token>` in subsequent file, sharing and enterprise API requests.

Minimal implementation outline: build `payload` as `{email: "user@example.com"}` for email-based login or a numeric `{client_id: 1000000000001}` for developer authorization, matching the current sample (replace with the actual application ID; Java can use `long`). Then build claims as `{time: current Unix timestamp in milliseconds, duration: 60, payload: payload}`, sign them with the enterprise JWT secret using HS256 / HmacSHA256, and pass the signed JWT as `userToken` or `jwt_token` in the corresponding URL. Use the same actual application ID in the `client_id` query parameter.

```java
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import javax.crypto.SecretKey;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

public final class BabelJwtExample {
    public static String createToken(Map<String, Object> payload) {
        String secret = System.getenv("BABEL_JWT_SECRET");
        if (secret == null || secret.isEmpty()) {
            throw new IllegalStateException("BABEL_JWT_SECRET is required");
        }
        SecretKey key = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
        Map<String, Object> claims = new HashMap<>();
        claims.put("time", System.currentTimeMillis());
        claims.put("duration", 60);
        claims.put("payload", payload);
        return Jwts.builder().claims(claims).signWith(key, Jwts.SIG.HS256).compact();
    }
}
```

This sample uses JJWT 0.12.x. Use matching versions of `jjwt-api`, `jjwt-impl`, and `jjwt-jackson`; see the [official JJWT documentation](https://github.com/jwtk/jjwt). The BabelBird example uses the secret's UTF-8 bytes. Confirm any different encoding with the implementation team instead of truncating, padding, or transforming the key. HS256 requires a key of at least 256 bits; request a suitable key if the library rejects it.

This function signs a token; it is not a login service or complete JWT validator. BabelBird's `time` and `duration` are custom fields, not the standard `exp` claim. Resolve the user identity from an authenticated server-side session, never log generated tokens, and validate authorization and expiry behavior against the target deployment.

## API Grouping

| Grouping | Main purpose | Typical entrance |
| --- | --- | --- |
| Authentication API | Developer account, OAuth callback, JWT login-free, Token acquisition and refresh | [Get token](https://www.babel.cc/public/babelwiki/en/api-post-api-token-do.html) |
| File API | File list, file information, upload and download, version, move copy, recycle bin, material library classification | [Get file list](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-list-dir.html) |
| Sharing API | Sharing link, sharing permissions, participants, attention reminders | [Get file sharing url](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-share-shareurl.html) |
| Enterprise API | Enterprise information, departments, members, enterprise logs | [Get current enterprise information](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-current.html) |
| Message and login API | Announcements, department discussions, JWT token login, common status codes | [JWT token login](https://www.babel.cc/public/babelwiki/en/api-get-account-tokenlogin-do.html) |

## Single interface page

Each API entry has an independent page, allowing developers to check paths, methods, parameters and return information by interface.

- [GET authentication interface one (login callback method)](https://www.babel.cc/public/babelwiki/en/api-get-api-authorize-do.html): `/api/authorize.do`
- [GET authentication interface two (login-free JWT token method)](https://www.babel.cc/public/babelwiki/en/api-get-api-authorizebyjwt-do.html): `/api/authorizeByJWT.do`
- [POST Get token](https://www.babel.cc/public/babelwiki/en/api-post-api-token-do.html): `/api/token.do`
- [POST refresh token](https://www.babel.cc/public/babelwiki/en/api-post-api-refreshtoken-do.html): `/api/refreshToken.do`
- [GET Get file list](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-list-dir.html): `/nd/api/file/list_dir` — **Request page starts at 0; response pages is the total page count**
- [GET Get file information](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-fileinfo.html): `/nd/api/file/fileinfo`
- [POST create folder](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-create-folder.html): `/nd/api/file/create_folder`
- [GET preupload file](https://www.babel.cc/public/babelwiki/en/api-get-api-file-preuploadfile-do.html): `/api/file/preUploadFile.do`
- [GET Get download file address](https://www.babel.cc/public/babelwiki/en/api-get-api-file-getfiledownloadurl-do.html): `/api/file/getFileDownloadUrl.do`
- [GET Get download multi-file address](https://www.babel.cc/public/babelwiki/en/api-get-api-file-downloadmultifiles-do.html): `/api/file/downloadMultiFiles.do`
- [GET Get download file thumbnail address](https://www.babel.cc/public/babelwiki/en/api-get-api-file-downloadthumbnail-do.html): `/api/file/downloadThumbnail.do`
- [POST modify file information](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-update-file.html): `/nd/api/file/update_file`
- [POST modify file name](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-rename.html): `/nd/api/file/rename`
- [POST delete file (to recycle bin)](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-remove-file.html): `/nd/api/file/remove_file`
- [POST remove file (from trash)](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-remove-from-trash.html): `/nd/api/file/remove_from_trash`
- [POST Empty Trash](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-empty-trash.html): `/nd/api/file/empty_trash`
- [POST restore file (from recycle bin)](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-restore-file.html): `/nd/api/file/restore_file`
- [GET Get all version information of the file](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-versions.html): `/nd/api/file/versions`
- [POST setting file current version](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-version.html): `/nd/api/file/version`
- [POST move file](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-move.html): `/nd/api/file/move`
- [POST copy file](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-copy.html): `/nd/api/file/copy`
- [POST copy file progress](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-copy-progress.html): `/nd/api/file/copy_progress`
- [GET file log](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-file-logs.html): `/nd/api/file/file_logs`
- [POST sets whether the user has permission to access the material library](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-set-user-access-material-library.html): `/nd/api/file/set_user_access_material_library`
- [POST Create Material Library Classification](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-create-material-class.html): `/nd/api/file/create_material_class`
- [POST create sub-material library](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-create-material-folder.html): `/nd/api/file/create_material_folder`
- [GET Get the share url of the file](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-share-shareurl.html): `/nd/api/share/shareurl`
- [GET Get the shared permission list](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-share-share-roles.html): `/nd/api/share/share_roles`
- [GET Get the sharing role that the user has permission to set for a single file](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-share-share-role-forfile.html): `/nd/api/share/share_role_forfile`
- [POST Create Link Share](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-share-open-link-share.html): `/nd/api/share/open_link_share`
- [POST close link sharing](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-share-close-link-share.html): `/nd/api/share/close_link_share`
- [POST set link sharing password](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-share-set-share-password.html): `/nd/api/share/set_share_password`
- [POST invite people to participate in sharing](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-share-invite-share.html): `/nd/api/share/invite_share`
- [GET Get all sharing participants](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-share-share-participants.html): `/nd/api/share/share_participants` — **Non-empty users sample and field types supplied**
- [POST set permission roles of sharing participants](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-share-set-participant-role.html): `/nd/api/file/set_participant_role` — **role_id uses integer roles[].id; babelshare_id uses string users[].babelshareId**
- [POST delete sharing participant](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-remove-share-participant.html): `/nd/api/file/remove_share_participant`
- [POST reminder](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-focus-file.html): `/nd/api/file/focus_file`
- [POST remove someone's attention](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-unfocus-file.html): `/nd/api/file/unfocus_file`
- [GET Get the list of users focusing on the file](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-user-focusfile.html): `/nd/api/file/user_focusfile`
- [GET Get the list of users who can focus on the file and mark the users who have focused on the file](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-file-user-can-focusfile.html): `/nd/api/file/user_can_focusfile` — **isFocusFile: 0 not following, 1 following**
- [GET Get current enterprise information](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-current.html): `/nd/api/enterprise/current`
- [GET Get information about all departments of the enterprise](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-departments.html): `/nd/api/enterprise/departments`
- [POST Create Enterprise Department](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-create-department.html): `/nd/api/enterprise/create_department`
- [GET Get department role list](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-dep-role.html): `/nd/api/enterprise/dep_role`
- [POST add department personnel](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-add-dep-mem.html): `/api/add_dep_mem.do` — **Result flags confirmed**
- [POST delete department personnel](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-remove-dep-mem.html): `/nd/api/enterprise/remove_dep_mem` — **Result flags confirmed**
- [GET to obtain information about your own department](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-mydeparments.html): `/nd/api/enterprise/mydeparments`
- [GET Get Department Members](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-departmentmembers.html): `/nd/api/enterprise/departmentmembers`
- [POST add enterprise members](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-add-ent-mem.html): `/api/add_ent_mem.do` — **Result flags confirmed**
- [POST update member information](https://www.babel.cc/public/babelwiki/en/api-post-api-updateuserinfo-do.html): `/api/updateUserInfo.do`
- [GET Get enterprise member information](https://www.babel.cc/public/babelwiki/en/api-get-api-getenterprisemember-do.html): `/api/getEnterpriseMember.do`
- [POST Get all members of the enterprise](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-enterprise-members.html): `/nd/api/enterprise/enterprise_members`
- [POST Get Enterprise Logs](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-enterprise-logs.html): `/nd/api/enterprise/enterprise_logs`
- [POST Release Announcement](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-enterprise-broadcast.html): `/nd/api/enterprise/broadcast`
- [GET Get published announcements](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-broadcast.html): `/nd/api/enterprise/broadcast`
- [POST Send Department Discussion](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-send-dep-discussion.html): `/nd/api/file/send_dep_discussion`
- [POST Get department discussion](https://www.babel.cc/public/babelwiki/en/api-post-nd-api-file-dep-discussion.html): `/nd/api/file/dep_discussion`
- [GET Get Enterprise Logs](https://www.babel.cc/public/babelwiki/en/api-get-nd-api-enterprise-enterprise-logs.html): `/nd/api/enterprise/enterprise_logs`
- [GET JWT token login](https://www.babel.cc/public/babelwiki/en/api-get-account-tokenlogin-do.html): `/account/tokenLogin.do`

## JWT Identity and Confidentiality

Explicitly pass the intended user's `email`, `phone` or `babelId` to `/api/authorizeByJWT.do`. The source permits an administrator identity when omitted. Do not omit identity or trust an unverified caller-supplied identity. Signing does not encrypt a JWT payload; avoid sensitive cleartext and do not log production tokens.