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_…— 권한을 제한한 스코프 키. 지정한 스코프 안에서만 동작하고 만료를 둘 수 있어요.op_p_…— 프로젝트 하나에 묶인 키. 콘솔 프로젝트의 API 키 탭에서 만들고, 이 키로 만드는 자원은 전부 그 프로젝트에 들어가고 비용은 팀이 내요.
스코프 (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 <앱이름> 한 줄이 제일 확실해요.
빌드를 그 앱 이미지 하나로 묶으려면 builds:*:이미지이름 (빌드 태그의 「:」 앞)처럼 적어요. 다른 이름의 이미지는 만들 수 없고 403 build_tag_out_of_scope가 돌아와요. GitHub·GitLab 자동 배포용으로 onpod ci init이 만드는 키가 이 형식이에요.
특정 팟·자산 하나만 허용하려면 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회용 접속 링크를 받아 방문자를 보내면 돼요.앱 안에서도 누가 들어왔는지 알 수 있어요. 보증할 때
identity_assertion 에 그쪽 서비스가 서명한 JWT를 함께 주면, 같은 회사의 잠긴 사이트로 가는 요청마다 X-Visitor-Assertion 헤더로 실어 앱에 전달해요. 앱은 그쪽 서비스의 공개키로 서명을 확인하면 돼요. 공개 사이트·다른 회사 사이트에는 싣지 않고, 바깥에서 같은 이름의 헤더를 보내도 지운 뒤에 붙여요.사람을 알려줄 때는 이메일 대신 식별자를 보내요. 방문자 보증(
subject_ref)과 초대 목록(invited_refs)에는 그쪽 서비스에서 만든 되돌릴 수 없는 값(이메일의 HMAC 해시나 내부 유저 ID)을 넣어 주세요. 이메일을 넣으면 거절해요. onpod은 그 값이 누구인지 모른 채 대조만 하니, 고객사 임직원 이메일이 이쪽에 저장되지 않아요. 회사·부서 판정은 tenant_ref·department_code 만으로 해요.사이트를 잠글 때는 어느 회사 것인지 먼저 알려주세요. 회사·부서·지정 인원으로 잠그려면
tenant_ref 가 필요해요. 내부 유저 ID는 보통 한 회사 안에서만 겹치지 않으니(사번처럼요), 초대 명단도 회사 단위로 갈라서 대조해요 — A 사 사번 1001을 초대해도 B 사 사번 1001은 못 들어와요. 회사를 안 알려주면 아무도 들어올 수 없는 사이트가 되니까, 그냥 만들지 않고 알려달라고 거절해요.