box-api

Box API

Box API는 엔터프라이즈 콘텐츠 관리 플랫폼인 Box에 저장된 파일·폴더를 프로그래밍 방식으로 다루는 REST API예요. 파일과 폴더를 만들고 읽고 수정하고 삭제하는 핵심 CRUD는 물론, 사용자 간 공유(Shared Link), 협업(Collaboration), 메타데이터, 웹훅(Webhook), 이벤트, 검색, 그리고 Box AI까지 폭넓게 지원해요. 모든 요청은 https://api.box.com/2.0을 기본 엔드포인트로 사용하고, 각 요청에는 반드시 OAuth 2.0 또는 JWT 방식으로 발급받은 액세스 토큰을 authorization: Bearer *** 헤더로 실어 보내야 해요. 공식 Box SDK(Python, Node, Java 등)가 잘 갖춰져 있어 curl로 직접 호출하거나 SDK를 골라서 쓸 수 있어요.

출처: 문서

본문

인증 (Authentication)

Box API는 두 가지 액세스 토큰 발급 방식을 제공해요.

  1. OAuth 2.0 인가 코드(Authorization Code) — 사람이 대신 사용자인 앱에 적합해요. 사용자가 Box 로그인 페이지에서 동의하면 code 를 돌려주고, 그 코드를 토큰 엔드포인트에 보내 액세스 토큰을 받아요.
  2. JWT(서버-서버) — 서비스 계정이 직접 자원에 접근하는 서버 애플리케이션에 적합해요. JWT 어서션(assertion)을 토큰 엔드포인트에 보내 액세스 토큰을 받아요.

인가 코드를 액세스 토큰으로 교환하는 예시예요.

curl -i -X POST "https://api.box.com/oauth2/token" \
     -H "content-type: application/x-www-form-urlencoded" \
     -d "client_id=[CLIENT_ID]" \
     -d "client_secret=[CLIENT_SECRET]" \
     -d "code=[CODE]" \
     -d "grant_type=authorization_code"

발급된 액세스 토큰은 유효 기간이 있으므로, 만료되면 refresh token으로 재발급(POST /oauth2/token 의 grant_type=refresh_token)하거나 JWT에서는 주기적으로 새로 발급받아야 해요. 필요 없어진 토큰은 POST /oauth2/revoke 로 폐기해요.

파일 (Files)

파일 정보 조회는 GET /files/{file_id}, 업로드는 POST /files/content, 수정은 PUT /files/{file_id}, 삭제는 DELETE /files/{file_id} 로 처리해요. 50MB가 넘는 큰 파일은 Chunk Upload API를 쓰는 걸 권장해요.

파일 업로드 예시예요. attributes(메타데이터) 부분이 반드시 file보다 앞에 와야 해요. 순서를 어기면 HTTP 400과 metadata_after_file_contents 오류가 나와요.

curl -i -X POST "https://upload.box.com/api/2.0/files/content" \
     -H "authorization: Bearer ***" \
     -H "content-type: multipart/form-data" \
     -F attributes='{"name":"Contract.pdf", "parent":{"id":"11446498"}}' \
     -F file=@<FILE_NAME>

업로드는 https://upload.box.com/api/2.0/files/content 를 쓰고, 나머지 CRUD는 https://api.box.com/2.0을 쓴다는 점이 포인트예요. 파일 내용 다운로드는 GET /files/{file_id}/content 로 받아요.

폴더 (Folders)

폴더 생성은 POST /folders 로 부모 폴더 ID와 이름을 지정해요. 폴더 ID 0은 루트 폴더를 뜻해요.

curl -i -X POST "https://api.box.com/2.0/folders" \
     -H "authorization: Bearer ***" \
     -H "content-type: application/json" \
     -d '{
       "name": "New Folder",
       "parent": {
         "id": "0"
       }
     }'

폴더 안에 있는 항목을 보려면 GET /folders/{folder_id} 를 호출하면 되는데, 이때 폴더 안의 첫 100개 항목까지 함께 반환돼요.

파일·폴더마다 공유 링크를 만들 수 있어요. PUT /files/{file_id}?fields=shared_link 로 shared_link 필드를 지정하면 되고, 접근 권한(access), 비밀번호(password), 만료 시각(unshared_at), 다운로드 허용 여부(can_download) 등을 함께 설정할 수 있어요.

curl -i -X PUT "https://api.box.com/2.0/files/32423234?fields=shared_link" \
     -H "authorization: Bearer ***" \
     -d '{
       "shared_link": {
         "access": "open",
         "password": "mypassword",
         "unshared_at": "2012-12-12T10:53:43-08:00",
         "permissions": {
           "can_download": false
         }
       }
     }'

access 값으로는 open(공개), company(회사 내), collaborators(협업자만) 등을 지정할 수 있어요.

웹훅 (Webhooks)

웹훅으로 파일·폴더에서 발생하는 이벤트(업로드, 다운로드, 미리보기, 삭제 등)를 외부 서버로 실시간 전달받을 수 있어요. POST /webhooks 로 타깃(target)과 이벤트 트리거(triggers), 콜백 주소(address)를 등록해요.

curl -i -X POST "https://api.box.com/2.0/webhooks" \
     -H "authorization: Bearer ***" \
     -H "content-type: application/json" \
     -d '{
       "target": {
         "id": "21322",
         "type": "file"
       },
       "address": "https://example.com/webhooks",
       "triggers": [
         "FILE.PREVIEWED"
       ]
     }'

이렇게 등록하면 파일이 미리보기될 때마다 address로 지정한 서버에 알림이 전달돼요. 등록된 웹훅 확인은 GET /webhooks, 수정은 PUT /webhooks/{id}, 삭제는 DELETE /webhooks/{id} 로 해요.

Box AI

Box API는 단순한 파일 관리에 그치지 않고, Box에 저장된 문서를 기반으로 요약·질의응답·구조화 추출을 하는 Box AI도 제공해요. LangChain, LlamaIndex, Pinecone 같은 프레임워크와 연동해 기업 문서에 대한 RAG 파이프라인을 만들 수도 있어요. 최신 엔드포인트와 모델 구성은 공식 문서에서 확인하는 게 좋아요.

더 알아보기 (Learn more)