Skip to Content
문서인증 모드

인증 모드 — External vs Embedded

Deplite를 호출하는 시스템은 API 토큰을 사용하는 External 모드로 인증해요.
워크플로우를 실행하는 서버나 기기는 1회용 설치 코드로 등록하는 Embedded 모드로 연결돼요.

한눈에 비교

ExternalEmbedded
방향내 시스템 → DepliteDeplite에 연결된 노드가 Workflow 실행
역할API를 호출하는 쪽Agent 또는 앱 내 실행 노드
자격API 토큰 (dpl_ + 64자리 16진수)1회용 설치 코드로 등록한 노드 신원
주요 사용처백엔드, CI, 자동화 스크립트서버 Agent, Android Embedded SDK

External 모드

외부 시스템이 Deplite API를 호출하는 모드예요.
이름 기반 실행은 POST /v1/run/{agentName}/{workflowName} 요청에 API 토큰을 첨부해요.

사용 흐름

  1. 조직 owner가 콘솔에서 필요한 Agent 또는 Workflow 권한의 API 토큰을 발급해요.
  2. 발급 직후 한 번만 표시되는 평문 토큰을 호출 환경에 안전하게 보관해요.
  3. 요청에 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.sh

on:이 없으면 외부 호출이 허용되지 않아요.
webhook: 아래에 refs가 없거나 빈 목록이면 모든 ref를 허용해요.

Embedded 모드

서버 Agent나 Android 앱이 Deplite에 등록되어 Workflow를 실행하는 모드예요.
등록에 사용하는 설치 코드는 한 번만 사용할 수 있어요.

사용 흐름

  1. 조직 owner가 콘솔에서 1회용 설치 코드를 발급해요.
  2. 서버 Agent는 deplite-agent install --code <1회용_설치_코드>로 등록할 수 있어요.
  3. Android Embedded SDK는 Deplite.register(installCode, name, ...)로 등록해요.
  4. 등록 후 Agent는 노드에서 Workflow를 실행해요.

API 토큰은 외부 호출에 사용하고, 1회용 설치 코드는 노드 등록에 사용해주세요.

클라이언트 지원 범위

클라이언트실행 경로
REST APIPOST /v1/run/{agentName}/{workflowName}로 이름 기반 호출
Flutter SDK 0.2.0Deplite.run(...)으로 이름 기반 호출
Android Embedded SDK 0.2.0노드 등록과 Embedded SDK 기능 제공. External 호출자는 REST 직접 호출
JS / iOS SDK 0.1.0이름 기반 run 미지원. REST 직접 호출 안내
deplite-agent서버 Agent 등록과 실행

관련 문서

최종 수정 일자: