BabelBirdBabelBird Docs
Section navigationDevelopment API Overview

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

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):

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

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

{
  "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.

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. 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
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

Scroll horizontally to view all columns

Single interface page

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

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.

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

Page Markdown · AI reading guide