토큰 접근 범위
토큰 접근 범위 조회 API는 해당 토큰이 접근할 수 있는 Agent와 워크플로우를 확인할 때 사용해요.
응답은 토큰의 grant 범위 안에서만 제공돼요.
https://api.deplite.io인증Authorization: Bearer dpl_...스코프agent · workflow · storage · release네 엔드포인트 모두 Bearer 토큰만 있으면 호출할 수 있고 특정 scope를 요구하지 않아요.
응답은 그 토큰의 grant 범위로만 한정돼요.
조직 전체 인벤토리를 반환하지 않고 새로운 권한을 부여하지도 않아요.
그 토큰으로 이미 호출할 수 있는 대상만 열거해요.
토큰 정보 조회
/v1/token호출자가 이미 토큰을 가지고 있으므로 토큰 메타데이터를 돌려줘요.
평문 토큰이나 해시는 응답에 포함되지 않아요.
응답
성공하면 HTTP 200과 아래 필드를 돌려줘요.
organizationIdstring · uuid토큰이 속한 조직 ID예요.
namestring토큰 이름이에요.
scopesarray이 토큰에 부여된 grant 목록이에요.
rateLimitobject분·시간·일 단위 호출 한도예요.
expiresAttimestampnull 가능만료 시각이에요.
오류
token_missingMissing bearer tokenRate limit exceeded for api token reads (minute: 61/60)공통 오류는 에러 코드에서 확인해주세요.
접근 가능한 Agent 목록 조회
/v1/agents토큰이 접근할 수 있는 Agent를 최근 등록 순으로 나열해요.
GET /v1/devices는 이 경로의 alias이며 응답이 같아요.
응답
성공하면 HTTP 200과 아래 배열을 돌려줘요.
idstring · uuidAgent ID예요.
namestringAgent 이름이에요.
hostnamestringnull 가능Agent가 보고한 호스트명이에요.
osstringnull 가능Agent가 보고한 운영체제예요.
agentVersionstringnull 가능Agent 버전이에요.
statusstring현재 연결 상태예요.
pendingconnecteddisconnectedrevokedlastSeenAttimestampnull 가능마지막 heartbeat 시각이에요.
enrolledAttimestampnull 가능등록 완료 시각이에요.
오류
token_missingMissing bearer tokenRate limit exceeded for api token reads (minute: 61/60)공통 오류는 에러 코드에서 확인해주세요.
실행 가능한 워크플로우 목록 조회
/v1/workflows토큰으로 실행할 수 있는 워크플로우를 이름 오름차순으로 나열해요.
removed 상태의 워크플로우와 Agent가 무효로 보고한 워크플로우는 목록에 나오지 않아요.
응답
성공하면 HTTP 200과 아래 배열을 돌려줘요.
idstring · uuid워크플로우 ID예요.
agentIdstring · uuid워크플로우가 속한 Agent ID예요.
namestring이름 기반 호출 경로에 넣는 워크플로우 이름이에요.
descriptionstringnull 가능워크플로우 설명이에요.
versionstringnull 가능정의에서 보고한 자유 형식 버전이에요.
paramsSchemaarraynull 가능호출 입력 파라미터 정의예요.
오류
token_missingMissing bearer tokenRate limit exceeded for api token reads (minute: 61/60)공통 오류는 에러 코드에서 확인해주세요.
grant에서 노출 범위로 매핑
/v1/agents와 /v1/workflows가 보여주는 대상은 토큰의 grant 조합으로 결정돼요.
| 토큰 grant | /v1/agents에 보이는 것 | /v1/workflows에 보이는 것 |
|---|---|---|
agent | grant에 적힌 Agent | 해당 Agent에서 호출이 허용된 워크플로우 |
workflow | grant에 지정된 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를 참고해주세요.
응답에서 의도적으로 빠지는 필드
민감 정보가 노출되지 않도록 다음 필드는 응답에 포함하지 않아요.
| 리소스 | 제외되는 필드 |
|---|---|
| Agent | publicKey |
| Workflow | secrets, 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/workflows | api_token.discover (metadata: { resource, count }) |
/v1/token | 기록하지 않음 |
| 읽기 rate limit에 걸린 호출 | rate_limit.block (scope: 'token_read'), 토큰당 윈도우마다 한 번 |
rate_limit.block을 윈도우당 한 번으로 제한해 폭주 호출이 audit 테이블에 쓰기 증폭을 일으키지 않도록 해요.