API 레퍼런스
Base URL
https://api.onpod.ai
모든 path 앞에 /v1 가 붙어요. 요청·응답 본문은 application/json. 기계가독 스펙: /v1/openapi.json
인증
version·manual·openapi.json을 뺀 모든 엔드포인트는 Authorization: Bearer <토큰> 가 필요해요. 토큰은 API 키 페이지에서 발급해요.
op_u_…— 계정/CLI 전권 토큰.opk_…— 권한을 제한한 스코프 키. 지정한 스코프 안에서만 동작하고 만료를 둘 수 있어요.
스코프 (opk_ 키 전용)
resource:action 형식이에요. resource ∈ {pods, builds, databases, volumes, static, buckets, registry, sandboxes, backups, billing, pod-templates, domains, partner, org}, action ∈ {read, write}. resource:* 는 읽기+쓰기, * 는 전권. write 스코프는 같은 리소스 read를 포함해요. 권한이 모자라면 403 scope_insufficient. 계정·키 관리(/me, /api-keys)는 스코프 키로 호출할 수 없어요.
🔴 팟 권한만으로는 배포가 안 돼요. 서버 빌드(POST /v1/builds)는 팟과 별개 리소스라 pods:* 가 안 덮어요. pods만 준 키는 상태·로그·exec·DB 조회가 전부 정상으로 되고 app update --build 에서만 403 builds:write 로 실패해서, 받는 쪽도 주는 쪽도 키를 의심하지 않게 돼요. 앱 하나를 통째로 맡길 거면 onpod key add --name <이름> --app <앱이름> 한 줄이 제일 확실해요.
특정 팟·자산 하나만 허용하려면 resource:action:ID 처럼 뒤에 대상을 붙여요 — 예: pods:write:팟ID, static:write:사이트주소. 이런 키는 정해둔 대상만 다룰 수 있고 새로 만들기·다른 대상은 전부 403 이에요. 팟 목록은 허용된 대상만 걸러서 보여주니, 이름으로 쓰는 CLI 명령(onpod app status 앱이름 등)은 그대로 돼요. 자동 확장 앱은 그룹 ID 하나로 소속 팟까지, 웹사이트는 주소(slug) 하나로 그 사이트 배포까지 함께 허용돼요. 콘솔의 「필요한 것만 허용 → 고른 것만」에서 클릭으로도 만들 수 있어요.
PUT /v1/partner/departments 로 부서 목록을 올리고(코드·상위코드 형태 그대로), PUT /v1/partner/departments/{코드}/policy 로 그 부서가 동시에 켜 둘 수 있는 앱 수를 정하거나 아예 막을 수 있어요. 사람마다는 POST·PATCH /v1/partner/users 의 department_code 로 붙여요. 한도에 닿으면 새로 만드는 것만 멈추고 이미 켜진 앱은 그대로 돌아가요.올라간 사이트를 아무나 못 보게 잠글 수도 있어요.
PUT /v1/partner/sites/{주소}/access 에 회사 전체·특정 부서·지정한 사람 중 하나를 정하면, 사이트 앞단에서 접근을 차단해 줘요(앱 안에 로그인 화면을 만들 필요가 없어요). 보는 사람은 그쪽 서비스의 평소 계정으로 로그인하고, 확인이 끝나면 POST /v1/partner/visitor-sessions 로 1회용 접속 링크를 받아 방문자를 보내면 돼요.사람을 알려줄 때는 이메일 대신 식별자를 보내요. 방문자 보증(
subject_ref)과 초대 목록(invited_refs)에는 그쪽 서비스에서 만든 되돌릴 수 없는 값(이메일의 HMAC 해시나 내부 유저 ID)을 넣어 주세요. 이메일을 넣으면 거절해요. onpod은 그 값이 누구인지 모른 채 대조만 하니, 고객사 임직원 이메일이 이쪽에 저장되지 않아요. 회사·부서 판정은 tenant_ref·department_code 만으로 해요.사이트를 잠글 때는 어느 회사 것인지 먼저 알려주세요. 회사·부서·지정 인원으로 잠그려면
tenant_ref 가 필요해요. 내부 유저 ID는 보통 한 회사 안에서만 겹치지 않으니(사번처럼요), 초대 명단도 회사 단위로 갈라서 대조해요 — A 사 사번 1001을 초대해도 B 사 사번 1001은 못 들어와요. 회사를 안 알려주면 아무도 들어올 수 없는 사이트가 되니까, 그냥 만들지 않고 알려달라고 거절해요.