인증 모드 — External vs Embedded
Deplite를 호출하는 시스템은 API 토큰을 사용하는 External 모드로 인증해요.
워크플로우를 실행하는 서버나 기기는 1회용 설치 코드로 등록하는 Embedded 모드로 연결돼요.
한눈에 비교
| External | Embedded | |
|---|---|---|
| 방향 | 내 시스템 → Deplite | Deplite에 연결된 노드가 Workflow 실행 |
| 역할 | API를 호출하는 쪽 | Agent 또는 앱 내 실행 노드 |
| 자격 | API 토큰 (dpl_ + 64자리 16진수) | 1회용 설치 코드로 등록한 노드 신원 |
| 주요 사용처 | 백엔드, CI, 자동화 스크립트 | 서버 Agent, Android Embedded SDK |
External 모드
외부 시스템이 Deplite API를 호출하는 모드예요.
이름 기반 실행은 POST /v1/run/{agentName}/{workflowName} 요청에 API 토큰을 첨부해요.
사용 흐름
- 조직 owner가 콘솔에서 필요한 Agent 또는 Workflow 권한의 API 토큰을 발급해요.
- 발급 직후 한 번만 표시되는 평문 토큰을 호출 환경에 안전하게 보관해요.
- 요청에
Authorization: Bearer dpl_...헤더를 첨부해요.
토큰 스코프
실행 권한은 Agent 또는 Workflow 범위로 선택해요.
파일 API가 필요하면 managed 스토리지용 storage 스코프를 별도로 사용할 수 있어요.
| 스코프 | 권한 |
|---|---|
agent | 지정한 Agent에서 호출이 허용된 Workflow 실행 |
workflow | 지정한 Agent와 Workflow만 실행 |
storage | 지정한 managed 스토리지 파일에 read·write·delete 권한으로 접근 |
조직 전체 실행 권한을 가진 토큰은 없어요.
토큰 발급 시 선택적으로 분·시간·일 호출 한도와 만료일을 설정할 수 있어요.
토큰은 환경과 용도에 맞는 최소 범위로 발급하고, 평문을 안전한 저장소에 보관해주세요.
호출 ref 제한
허용할 ref는 토큰의 allowedRefs 옵션으로 설정하지 않아요.
워크플로우 YAML의 on.webhook.refs가 호출 가능한 ref를 선언하고, 콘솔에서는 그 범위를 더 좁힐 수 있어요.
실제 허용 ref는 YAML 선언과 콘솔에서 좁힌 ref 목록을 모두 만족해야 해요.
콘솔에서 호출을 잠그거나 범위를 좁힐 수는 있지만, YAML에서 열지 않은 호출을 새로 허용할 수는 없어요.
name: deploy
on:
webhook:
refs: [main, "release/*"]
steps:
- run: ./deploy.shon:이 없으면 외부 호출이 허용되지 않아요.
webhook: 아래에 refs가 없거나 빈 목록이면 모든 ref를 허용해요.
Embedded 모드
서버 Agent나 Android 앱이 Deplite에 등록되어 Workflow를 실행하는 모드예요.
등록에 사용하는 설치 코드는 한 번만 사용할 수 있어요.
사용 흐름
- 조직 owner가 콘솔에서 1회용 설치 코드를 발급해요.
- 서버 Agent는
deplite-agent install --code <1회용_설치_코드>로 등록할 수 있어요. - Android Embedded SDK는
Deplite.register(installCode, name, ...)로 등록해요. - 등록 후 Agent는 노드에서 Workflow를 실행해요.
API 토큰은 외부 호출에 사용하고, 1회용 설치 코드는 노드 등록에 사용해주세요.
클라이언트 지원 범위
| 클라이언트 | 실행 경로 |
|---|---|
| REST API | POST /v1/run/{agentName}/{workflowName}로 이름 기반 호출 |
| Flutter SDK 0.2.0 | Deplite.run(...)으로 이름 기반 호출 |
| Android Embedded SDK 0.2.0 | 노드 등록과 Embedded SDK 기능 제공. External 호출자는 REST 직접 호출 |
| JS / iOS SDK 0.1.0 | 이름 기반 run 미지원. REST 직접 호출 안내 |
deplite-agent | 서버 Agent 등록과 실행 |