인증 · 권한Authentication
읽기는 API 키, 원격 설정 쓰기는 OAuth2 클라이언트 자격(client credentials) 과 계약에서 부여된 범위(scope)가 필요해요.
API 키 (읽기)
머신 소유자(계약 당사자)가 소유자 콘솔에서 발급해요. 키는 머신 단위 또는 조직 단위로 범위가 고정되고, 발급 뒤 평문은 한 번만 보여요.
| 접두 | 용도 | 예 |
|---|---|---|
vdas_pk_live_ | 운영 읽기 | vdas_pk_live_8f3a… |
vdas_pk_test_ | 샌드박스(견본 머신 3대, 가짜 샷) | vdas_pk_test_01c2… |
GET /v1/public/machines
Authorization: Bearer vdas_pk_live_8f3a…OAuth2 클라이언트 자격 (쓰기)
원격 설정 쓰기는 API 키로는 할 수 없어요. 계약서에 적힌 범위로 클라이언트를 등록하고 토큰을 받아요. 토큰 수명은 1시간, 범위는 토큰에 박혀요.
POST /v1/public/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=cl_7d1f…
&client_secret=…
&scope=settings:write:lighting settings:write:standby| scope | 허용되는 것 |
|---|---|
machines:read | 머신·펌웨어 상태 (API 키 기본) |
shots:read | 샷 기록·곡선 (API 키 기본) |
telemetry:read | SSE 스트림 (API 키 기본) |
settings:read | 허용 목록 설정의 현재 값 |
settings:write:lighting | shot_light_mode · display_brightness · display_auto_off_s · ambient_* |
settings:write:standby | heater_standby_type |
webhooks:manage | 웹훅 등록·삭제 |
키의 범위와 머신 귀속
키는 발급한 소유자의 머신에만 닿아요. 다른 소유자의 시리얼을 넣으면 404 예요 (존재 여부를 알려 주지 않아요). 머신이 양도되면 이전 소유자의 키는 그 머신에 대해 즉시 404 가 돼요.
키 회전 · 폐기
POST /v1/public/api-keys # 새 키 발급 (평문 1회 응답)
GET /v1/public/api-keys # 목록 (접두 · 마지막 사용 시각)
DELETE /v1/public/api-keys/{key_id} # 즉시 폐기Reads use an API key. Writing remote settings needs OAuth2 client credentials with scopes granted by contract.
API keys
Issued by the machine owner in the owner console, scoped to a machine or an organisation. The plaintext is shown once. Prefixes: vdas_pk_live_ (production reads), vdas_pk_test_ (sandbox with three sample machines).
OAuth2 client credentials
POST /v1/public/oauth/token
grant_type=client_credentials&client_id=…&client_secret=…
&scope=settings:write:lighting settings:write:standby| scope | Grants |
|---|---|
machines:read · shots:read · telemetry:read | default read scopes |
settings:read | current allow-listed values |
settings:write:lighting | shot light, display brightness/auto-off, ambient |
settings:write:standby | heater standby type |
webhooks:manage | register / delete webhooks |