BabelBirdBabelBird Docs

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.

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 payload. For user login-free access, use email, phone or babelId; for /api/authorizeByJWT.do, use client_id

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>, 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: first build payload, for example {email: "user@example.com"} for user login-free access or {client_id: "<CLIENT_ID>"} for developer authorization; then build JWT claims as {time: current Unix timestamp in milliseconds, duration: 60, payload: payload}; sign the claims with the enterprise JWT secret using HS256 / HmacSHA256; finally pass the signed JWT string as userToken or jwt_token in the corresponding URL.

import java.nio.charset.StandardCharsets;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

public class BabelJwtExample {
    // Obtain this from the enterprise admin console or delivery materials.
    // The example value must be replaced and must not be used in production.
    private static final String JWT_SECRET = "REPLACE_WITH_ENTERPRISE_JWT_SECRET";

    public static void main(String[] args) throws Exception {
        Map<String, Object> user = new HashMap<>();
        user.put("email", "user@example.com");
        // Or use phone / babelId according to the enterprise account system:
        // user.put("phone", "13800000000");
        // user.put("babelId", "EMP001");

        String userToken = createTokenJWT(user);
        System.out.println("userToken=" + userToken);
        System.out.println("/account/tokenLogin.do?userToken=" + userToken);

        Map<String, Object> clientInfo = new HashMap<>();
        clientInfo.put("client_id", "REPLACE_WITH_CLIENT_ID");
        String jwtToken = createTokenJWT(clientInfo);
        System.out.println("/api/authorizeByJWT.do?response_type=code&client_id=REPLACE_WITH_CLIENT_ID&jwt_token=" + jwtToken);
    }

    public static String createTokenJWT(Map<String, Object> payload) {
        Map<String, Object> claims = new HashMap<>();
        claims.put("time", new Date().getTime());
        claims.put("duration", 60);
        claims.put("payload", payload);

        SecretKey key = generalKey();
        JwtBuilder builder = Jwts.builder()
            .setClaims(claims)
            .signWith(SignatureAlgorithm.HS256, key);
        return builder.compact();
    }

    public static Claims parseTokenJWT(String jwt) {
        SecretKey key = generalKey();
        Claims claims = Jwts.parser()
            .setSigningKey(key)
            .parseClaimsJws(jwt)
            .getBody();

        Long time = ((Number) claims.get("time")).longValue();
        Long duration = ((Number) claims.get("duration")).longValue();
        if (new Date().getTime() - time > 1000L * duration) {
            throw new IllegalStateException("JWT token expired");
        }
        return claims;
    }

    private static SecretKey generalKey() {
        byte[] encodedKey = JWT_SECRET.getBytes(StandardCharsets.UTF_8);
        return new SecretKeySpec(encodedKey, 0, encodedKey.length, "HmacSHA256");
    }
}

If the project uses an older jjwt version, the structure can remain close to this example. If it uses the newer split dependencies such as jjwt-api, jjwt-impl and jjwt-jackson, adjust the signing and parsing methods according to the library version. During integration, generate and parse the token on the server first, then use it with /account/tokenLogin.do or /api/authorizeByJWT.do to verify login and authorization behavior.

API Grouping

Grouping Main purpose Typical entrance
Authentication API Developer account, OAuth callback, JWT login-free, Token acquisition and refresh Get token
File API File list, file information, upload and download, version, move copy, recycle bin, material library classification Get file list
Sharing API Sharing link, sharing permissions, participants, attention reminders Get file sharing url
Enterprise API Enterprise information, departments, members, enterprise logs Get current enterprise information
Message and login API Announcements, department discussions, JWT token login, common status codes JWT token login

Single interface page

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

BabelBird capabilities may change by product version, licensed modules and deployment configuration; actual availability depends on the deployed environment and administrator settings.