API 키

API 키는 dAio Business에 대한 프로그래밍 방식의 접근을 열어줍니다. 이를 통해 고객님의 애플리케이션, 스크립트, 시스템이 웹 인터페이스를 거치지 않고 플랫폼에 직접 질의할 수 있습니다 — 날씨, 대기질, 꽃가루, 해양 상태, 산업 인텔리전스 등의 데이터. 이는 통합을 산업화하기 위한 진입점입니다. ERP에 데이터를 공급하고, 업무 처리를 트리거하며, 고객님의 자체 대시보드에 예보를 표시할 수 있습니다.

각 키는 고객님의 조직을 대신하여 호출을 인증하고 그 권한을 상속합니다. Webhook과 결합하면 완전한 채널을 갖추게 됩니다. API를 통해 필요할 때 dAio에 질의하고, Webhook을 통해 dAio가 실시간으로 알려줍니다.

팁: 용도별(서비스, 환경, 파트너)로 별도의 키를 생성하세요. 하나를 폐기하더라도 다른 키에는 영향을 주지 않으며, 어떤 통합이 무엇을 소비하는지 정확히 추적할 수 있습니다.

API 키의 용도

필요	API 키로 가능한 일
통합	사람의 개입 없이 dAio를 고객님의 정보 시스템(ERP, CMMS, BI)에 연결합니다.
자동화	계획된 처리(예보의 일일 수집, 위험 스코어링)를 실행합니다.
배포	dAio 데이터를 고객님의 애플리케이션이나 포털에 표시합니다.
통제된 공유	사용자 계정을 생성하지 않고도 파트너에게 제한적이고 폐기 가능한 접근 권한을 부여합니다.

참고: API 접근은 유료 플랜에 한정됩니다. 활성 구독이 없는 조직은 모든 호출에 대해 403 응답(« API access requires a paid plan »)을 받습니다.

키 생성하기

키 생성은 조직의 소유자(owner)와 관리자(admin)에게만 허용 됩니다. 다른 역할은 키를 생성하거나 폐기할 수 없습니다.

1. 설정 > API 키 로 이동합니다.
2. 오른쪽 상단의 새 키 를 클릭합니다.
3. 키의 용도를 식별하는 설명적인 이름 을 입력합니다(예: 「운영 백엔드」, 「Power BI 커넥터」, 「파트너 X 통합」).
4. 생성 을 클릭합니다.
5. 전체 키가 녹색 배너에 표시됩니다. 복사 버튼을 사용해 즉시 복사 하세요.

주의: 전체 키는 생성 시점에 단 한 번만 표시됩니다. 그 이후로는 다시 표시되지 않습니다 — 플랫폼은 암호화된 지문만 보관합니다. 분실하면 새 키를 생성해야 합니다. 지체 없이 시크릿 관리 도구(Vault, AWS Secrets Manager, 암호화된 환경 변수)에 저장하세요.

생성된 후, 키는 목록에 이름, 접두사(노출하지 않고 식별하기 위한 첫 몇 글자), 상태 표시기(녹색 = 활성, 빨간색 = 폐기됨), 마지막 사용 날짜 와 함께 표시됩니다.

키 사용하기

dAio API로 향하는 모든 요청은 HTTP 헤더 X-API-Key 에 키를 포함해야 합니다. API의 기본 주소는 https://api-dev.daio.app 이며, B2B 엔드포인트에는 /api/v1/ 접두사가 붙습니다.

curl -H "X-API-Key: VOTRE_CLE_API" \
  "https://api-dev.daio.app/api/v1/weather/current?lat=48.8566&lon=2.3522"

주의: 기대되는 헤더는 정확히 X-API-Key 이며, Authorization: Bearer 가 아닙니다. 유효하지 않거나 폐기되었거나 다른 헤더로 전달된 키는 401 응답(« Invalid API key »)을 반환합니다.

엔드포인트의 전체 목록(날씨, 시간별 예보, 대기질, 꽃가루, 해양, 배치 처리)과 응답 형식은 API 기술 문서 를 참조하세요.

속도 제한

서비스의 안정성을 보장하기 위해, 각 키에는 시간당 속도 제한 이 적용됩니다. 카운터는 각 키마다 독립적이며 매시간 초기화됩니다.

플랜	시간당 요청 수
Free / no subscription	API 접근 없음
Solo · Team · Enterprise(dAio Business)	20 000

제한에 도달하면 API는 429 응답(« Rate limit exceeded »)을 반환하며, 재시도까지 대기할 시간을 나타내는 Retry-After 헤더가 함께 제공됩니다.

참고: 이 시간당 제한은 고객님의 요금제에 포함된 월간 요청 할당량 과는 별개입니다. 플랜별 할당량의 상세 내용은 구독 섹션에서 확인하세요.

키 회전하기

회전(rotation) 은 키의 이름과 목록 내 위치를 유지하면서 키를 재생성합니다. 전체 통합을 다시 구성하지 않고도 시크릿을 주기적으로 갱신하기 위해 사용하세요.

1. 목록에서 해당 키 옆의 회전 아이콘(원형 화살표)을 클릭합니다.
2. 작업을 확인합니다.
3. 새 값 이 한 번만 표시됩니다 — 즉시 복사하세요.
4. 이 새 값으로 애플리케이션을 업데이트합니다.

팁: 90일마다 회전을 계획하고, 시크릿에 접근했던 직원이 퇴사한 후나 유출이 의심되는 경우에는 반드시 실행하세요.

키 폐기하기

침해되었거나 사용되지 않는 키의 접근을 차단하려면:

1. 목록에서 해당 키 옆의 삭제 아이콘(휴지통)을 클릭합니다.
2. 폐기를 확인합니다.

폐기는 즉각적이며 되돌릴 수 없습니다. 폐기된 키를 사용하는 모든 요청은 즉시 401 응답을 받습니다. 키는 이력 차원에서 폐기됨 으로 표시되어 목록에 계속 표시됩니다.

키 보안

API 키는 비밀번호와 동등합니다. 이를 소지한 사람은 누구나 고객님 조직의 권한으로 API에 질의할 수 있습니다.

주의: 비공개라 하더라도 키를 소스 코드나 Git 저장소에 절대 커밋하지 마세요. 실수로 저장소에 푸시된 키는 침해된 것으로 간주됩니다 — 지체 없이 폐기하고 회전하세요. 이메일, 메신저, 지원 티켓을 통해 평문으로 전달하는 것도 결코 하지 마세요.

• 키는 코드에 하드코딩하지 말고 시크릿 관리 도구나 환경 변수에 저장 하세요.
• 클라이언트 측(웹 앱, 모바일, 브라우저 JavaScript)에서 노출하지 마세요: API 호출은 고객님의 서버에서 출발해야 합니다.
• 분리하세요: 환경(운영, 검수)별로, 용도별로 하나의 키를 사용합니다.
• 마지막 사용 날짜를 모니터링하세요: 오랫동안 비활성 상태인 키는 폐기해야 할 키입니다.

모범 사례

• 각 키가 무엇을 지원하는지 한눈에 식별할 수 있도록, 용도와 환경에 따라 각 키에 명시적으로 이름을 붙이세요.
• 최소 권한을 적용하세요: 모든 통합이 공유하는 단일 키 대신 전용이고 폐기 가능한 키를 생성합니다.
• 90일마다 회전을 자동화하고 직원 퇴사 절차에 통합하세요.
• 클라이언트 측에서 429 를 처리하세요: Retry-After 헤더를 준수하고 요청을 연속으로 보내기보다 호출을 고르게 분산하세요.
• 침해가 의심되는 키는 즉시 폐기하세요 — 폐기는 지체 없이 효력이 발생합니다.
• 보안 감사를 원활하게 진행하기 위해, 어떤 키가 무엇에 쓰이고 누가 책임자인지를 내부에 문서화하세요.

팁: 완전한 통합을 위해 API 키를 Webhook과 연계하세요 — 필요할 때 dAio에 질의하고, dAio가 이벤트를 실시간으로 알리도록 하세요.