Skip to Content
문서API 레퍼런스토큰 접근 범위

토큰 접근 범위

토큰 접근 범위 조회 API는 해당 토큰이 접근할 수 있는 Agent와 워크플로우를 확인할 때 사용해요.
응답은 토큰의 grant 범위 안에서만 제공돼요.

Base URLhttps://api.deplite.io인증Authorization: Bearer dpl_...스코프agent · workflow · storage · release

네 엔드포인트 모두 Bearer 토큰만 있으면 호출할 수 있고 특정 scope를 요구하지 않아요.

응답은 그 토큰의 grant 범위로만 한정돼요.
조직 전체 인벤토리를 반환하지 않고 새로운 권한을 부여하지도 않아요.
그 토큰으로 이미 호출할 수 있는 대상만 열거해요.

토큰 정보 조회

GET/v1/token권한 scope 무관

호출자가 이미 토큰을 가지고 있으므로 토큰 메타데이터를 돌려줘요.
평문 토큰이나 해시는 응답에 포함되지 않아요.

응답

성공하면 HTTP 200과 아래 필드를 돌려줘요.

organizationIdstring · uuid

토큰이 속한 조직 ID예요.

namestring

토큰 이름이에요.

scopesarray

이 토큰에 부여된 grant 목록이에요.

rateLimitobject

분·시간·일 단위 호출 한도예요.

expiresAttimestampnull 가능

만료 시각이에요.

오류

401
token_missing
Bearer 토큰이 없어요.
Missing bearer token
429
토큰 읽기 요청 한도를 초과했어요.
Rate limit exceeded for api token reads (minute: 61/60)

공통 오류는 에러 코드에서 확인해주세요.

접근 가능한 Agent 목록 조회

GET/v1/agents권한 scope 무관

토큰이 접근할 수 있는 Agent를 최근 등록 순으로 나열해요.
GET /v1/devices는 이 경로의 alias이며 응답이 같아요.

응답

성공하면 HTTP 200과 아래 배열을 돌려줘요.

idstring · uuid

Agent ID예요.

namestring

Agent 이름이에요.

hostnamestringnull 가능

Agent가 보고한 호스트명이에요.

osstringnull 가능

Agent가 보고한 운영체제예요.

agentVersionstringnull 가능

Agent 버전이에요.

statusstring

현재 연결 상태예요.

허용 값pendingconnecteddisconnectedrevoked
lastSeenAttimestampnull 가능

마지막 heartbeat 시각이에요.

enrolledAttimestampnull 가능

등록 완료 시각이에요.

오류

401
token_missing
Bearer 토큰이 없어요.
Missing bearer token
429
토큰 읽기 요청 한도를 초과했어요.
Rate limit exceeded for api token reads (minute: 61/60)

공통 오류는 에러 코드에서 확인해주세요.

실행 가능한 워크플로우 목록 조회

GET/v1/workflows권한 scope 무관

토큰으로 실행할 수 있는 워크플로우를 이름 오름차순으로 나열해요.
removed 상태의 워크플로우와 Agent가 무효로 보고한 워크플로우는 목록에 나오지 않아요.

응답

성공하면 HTTP 200과 아래 배열을 돌려줘요.

idstring · uuid

워크플로우 ID예요.

agentIdstring · uuid

워크플로우가 속한 Agent ID예요.

namestring

이름 기반 호출 경로에 넣는 워크플로우 이름이에요.

descriptionstringnull 가능

워크플로우 설명이에요.

versionstringnull 가능

정의에서 보고한 자유 형식 버전이에요.

paramsSchemaarraynull 가능

호출 입력 파라미터 정의예요.

오류

401
token_missing
Bearer 토큰이 없어요.
Missing bearer token
429
토큰 읽기 요청 한도를 초과했어요.
Rate limit exceeded for api token reads (minute: 61/60)

공통 오류는 에러 코드에서 확인해주세요.

grant에서 노출 범위로 매핑

/v1/agents와 /v1/workflows가 보여주는 대상은 토큰의 grant 조합으로 결정돼요.

토큰 grant/v1/agents에 보이는 것/v1/workflows에 보이는 것
agentgrant에 적힌 Agent해당 Agent에서 호출이 허용된 워크플로우
workflowgrant에 지정된 Agent지정한 워크플로우
storage만 있는 토큰빈 배열빈 배열
release만 있는 토큰빈 배열빈 배열

App 릴리스 토큰 권한

release grant는 조직 전체 또는 appIds에 지정한 앱에 적용돼요.
permissions에는 필요한 작업을 골라 넣어요.

권한허용되는 작업
create파일 릴리스 생성. 파일 binding의 storage read 권한도 필요해요.
publish릴리스 게시
yank게시 릴리스 회수

아티팩트 업로드에는 storage write 권한이 필요해요.
릴리스 API에서 지원하는 필드와 응답은 App Deploy API에서 확인해주세요.

Job 조회 권한

Job 상태와 로그는 Job을 생성한 실행 요청과 같은 API Token으로만 조회할 수 있어요.
실행 요청을 보낼 때 agent 또는 workflow grant가 필요하고, 조회 경로는 잡 조회 API를 참고해주세요.

응답에서 의도적으로 빠지는 필드

민감 정보가 노출되지 않도록 다음 필드는 응답에 포함하지 않아요.

리소스제외되는 필드
AgentpublicKey
Workflowsecrets, secretsKeys, steps

paramsSchema는 비밀이 아닌 입력 파라미터 정의라서 호출 편의를 위해 응답에 포함돼요.
각 항목은 name, type(string, number, boolean, enum)을 가져요.
required, default, pattern, options, min, max, description은 선택 항목이에요.
워크플로우 버전은 자유 문자열이며 semver를 강제하지 않아요. 예를 들어 1.2.0, 2024-06-rc1 같은 값이 올 수 있고 정의에 없으면 null이에요.

에러와 읽기 rate limit

HTTP상황
401토큰 누락·무효·폐기·만료
429읽기 rate limit 초과

읽기 rate limit은 토큰의 rateLimit 실행 한도와 별개예요.
기본값은 토큰당 분당 60회이며 서버 환경 변수 API_TOKEN_READ_RATE_LIMIT_PER_MINUTE로 조정해요.

{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for api token reads (minute: 61/60)", "scope": "token_read", "window": "minute", "limit": 60, "observed": 61 }

셀프 호스팅에서는 카운터가 인스턴스 메모리에 있어 다중 인스턴스 배포 시 인스턴스당 한도로 동작해요.
전역 한도가 아니라 목록 열거 폭주를 늦추는 완화책으로 봐주세요.

감사 로그

호출기록되는 audit 로그
/v1/agents, /v1/devices, /v1/workflowsapi_token.discover (metadata: { resource, count })
/v1/token기록하지 않음
읽기 rate limit에 걸린 호출rate_limit.block (scope: 'token_read'), 토큰당 윈도우마다 한 번

rate_limit.block을 윈도우당 한 번으로 제한해 폭주 호출이 audit 테이블에 쓰기 증폭을 일으키지 않도록 해요.

관련 문서

최종 수정 일자: