Box
Ingests files and folders from a Box account, using the Box event-stream API for incremental sync. Per-file and per-folder permissions are mapped to workspace access groups.
variant=info text="Cloud storage" variant=success text="OAuth" variant=success text="Maps ACLs"
What gets ingested
| Element | Mapped to |
|---|---|
| Box file | _FileEntry + _Blob |
| Box folder | _Folder |
| Folder tree (parent → child) | _HasChild edges |
| File metadata (SequenceId, SHA-1, description, size, version) | Properties on _FileEntry |
| Move / rename / delete events | Graph mutations (re-parent, rename, delete) |
Authentication
- Type: OAuth 2.0 (per-user).
- The user clicks Connect Box → Box consent screen → returns a short-lived access token + long-lived refresh token. The workspace stores both encrypted; the refresh token is exchanged automatically before expiry.
sequenceDiagram
participant U as User
participant WS as Workspace
participant Box as Box OAuth
U->>WS: Click "Connect Box"
WS->>Box: Redirect to /authorize
Box->>U: Consent screen
U->>Box: Approve
Box->>WS: code (redirect)
WS->>Box: Exchange code for tokens
Box->>WS: access_token + refresh_token
WS->>WS: Store encrypted
Access control mapping
| Source | Carried into the graph? |
|---|---|
| Per-user Box access | Yes — each connected user gets their own _AccessGroup (TaskUserGroupName). |
| Folder/file collaborator role | Yes — folder and file ACLs are mapped via AddPermissionToItem. |
| Public/shared links | Yes — items shared publicly map onto _AccessGroup.Public. |
Sync cadence
- Default cron: every 15 minutes.
- Incremental sync: the connector tracks a
streamPositionper user. On each run it pages the Box event stream (events?stream_position=...) and applies create / update / move / delete events to the graph.
First run vs. subsequent runs
First run = initial full sync; subsequent runs = events only. The initial sync recursively lists folders; later runs only need the event delta, which keeps Box throttling impact low.