Box Port

Purpose

This is the Harbor reference integration for the Box API.

Use it when:

• building Box actions in Harbor
• extending the Dock / Hub Box entry
• teaching Codex or OpenClaw how to map a storage API into Harbor Ports and Harbor Actions without turning Harbor into a generic content proxy

Harbor Port worksheet

Product

• Product: Box API
• Publisher slug: box
• Publisher name: Box
• Category: Storage
• Tags: box, storage, files, folders, content

Safe Harbor Port metadata

• Kind: http_api
• Label: Box API
• Description: Box API connection managed locally through Harbor.
• Base URL: https://api.box.com/2.0/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Box fits Harbor well because:

• every starter action stays on one fixed origin
• folder and file routes are explicit and reviewable
• Harbor can model folder and file IDs as bounded path inputs
• pagination and sort controls fit Harbor's typed query input model
• folder creation maps cleanly to a bounded JSON request body

Good Harbor Box starter actions:

• fixed GET reads for folder browsing and file inspection
• explicit POST writes for folder creation
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for writes
• resultMode: "json_summary" for all starter actions

Avoid for now:

• large enterprise admin surfaces
• uploads, downloads, and file content transfer as a first-wave action set
• generic forwarding across the whole Box API
• broad write coverage before operator review

Starter Box actions

Automatic read actions

• list-folder-items -> GET /folders/{folderId}/items
• get-file -> GET /files/{fileId}

Approval-friendly write actions

• create-folder -> POST /folders

Why these actions

These routes fit Harbor's current safe model well because they:

• cover the common operator loop of browsing folders, confirming file IDs, and creating a new folder
• keep the route surface small and explicit
• use Harbor's Action Model for typed path and query values
• map cleanly to Box's bearer-token auth model
• give Harbor a useful storage integration without widening into content upload or download flows yet

Action Model notes

At execution time, callers should supply values by location:

• input.path and input.query for list-folder-items
• input.path and optionally input.query for get-file
• input.body for create-folder

Example folder listing request:

{
  "path": {
    "folderId": "0"
  },
  "query": {
    "limit": 100,
    "sort": "name",
    "direction": "ASC"
  }
}

Example file lookup request:

{
  "path": {
    "fileId": "12345"
  },
  "query": {
    "fields": "name,size,modified_at,path_collection"
  }
}

Example folder creation request:

{
  "body": {
    "name": "Harbor Drafts",
    "parent": {
      "id": "0"
    }
  }
}

For create-folder, keep the JSON body bounded to the fields you actually intend to use, such as:

• name
• parent.id
• sync_state
• folder_upload_email.access

Suggested operator workflow

1. Import the Box Dock entry from Dock / Hub.
2. Configure the local Box bearer token in Harbor Node.
3. Use list-folder-items to discover folder structure and relevant IDs.
4. Use get-file to inspect file metadata and confirm explicit file IDs.
5. Keep create-folder on require_approval unless there is a clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing Box Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed Box routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Box token
• widen Box into a generic file or content proxy
• hide Box route names behind vague labels
• add broad write, upload, or delete coverage without review

Current update strategy

For now, Box updates are manual:

• update the Dock / Hub Box integration document in apps/hub/catalog/integrations/box/box-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Scope notes

This starter set intentionally focuses on metadata and folder structure.

That means:

• folder browsing uses explicit folder IDs
• file inspection returns metadata, not file content
• folder creation is the only seeded write action
• uploads, downloads, and deletions should be added later only when they remain fixed and reviewable

Official reference starting points

• Box API reference: https://developer.box.com/reference/
• List items in folder: https://developer.box.com/reference/get-folders-id-items/
• Get file information: https://developer.box.com/reference/get-files-id/
• Create folder: https://developer.box.com/reference/post-folders/