인증

Deeply API는 API 계정 정보, Access Token, Refresh Token을 함께 사용합니다. 각 자격 증명의 역할이 다르므로 구분해서 사용하는 것이 중요합니다.

토큰 역할#

• API 계정 정보: 토큰 발급에만 사용하는 username과 password
• Access Token: 일반 API 요청과 WebSocket 연결에 사용하는 Bearer 토큰
• Refresh Token: 토큰 재발급에만 사용하는 토큰

일반 엔드포인트에는 API 계정 정보나 Refresh Token을 보내지 말고, Access Token만 사용하세요.

API 계정 정보 받기#

API 계정 정보는 대시보드에서 발급되지 않습니다. contact@deeplyinc.com으로 요청하시면 메일로 전달해 드립니다. 전달받은 계정 정보는 연동 시스템의 비밀 값으로 보관하고, 소스 코드나 메신저에 공유하지 마세요.

토큰 수명 주기#

1. username과 password로 토큰 발급을 호출해 access_token과 refresh_token을 받습니다.
2. 일반 API 요청과 WebSocket 연결의 Authorization 헤더에 access_token을 담아 보냅니다.
3. Access Token이 만료되면(expires_in초 후, 기본 3600초) Authorization: Bearer YOUR_REFRESH_TOKEN으로 토큰 재발급을 호출하고, 저장한 두 토큰을 새 값으로 교체합니다.
4. Refresh Token이 만료되면(기본 30일) 토큰 발급을 다시 호출합니다.

Access Token 사용 방법#

모든 일반 API 요청의 Authorization 헤더에 Bearer 형식으로 Access Token을 포함해 주세요.

Authorization: Bearer YOUR_ACCESS_TOKEN

요청 예시#

curl -X GET "http://{{EDGE_IP}}:8100/api/v1/events" -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

이 페이지의 예시는 API 빠른 시작에서 안내하는 로컬 기본 호스트를 사용합니다. 같은 요청을 공개 HTTPS 환경에서 검증하려면 호스트를 https://openapi.deeplyinc.com로 바꿔 테스트해 주세요.

Access Token 발급이 필요할 때#

아직 토큰이 없다면 API 계정 정보로 토큰 발급을 호출하세요. Access Token이 만료되었다면 Authorization: Bearer YOUR_REFRESH_TOKEN으로 토큰 재발급을 호출하세요.

오류 응답#

인증에 실패하면 다음과 같은 응답을 받을 수 있습니다.

• 401: 인증 실패 - 만료된 토큰
  • Access Token이 만료되었을 때 반환됩니다. 토큰을 발급받은 세션이 종료된 경우에도 만료 시각과 관계없이 반환됩니다. 새 토큰을 재발급해 세션을 갱신해 주세요.
• 401: 인증 실패 - 잘못된 키
  • Access Token이 유효하지 않을 때 반환됩니다. 계정이 비활성화된 경우에도 반환됩니다. 토큰 값을 확인한 뒤 다시 시도해 주세요.
• 403: 권한 없음 - 토큰 누락
  • 요청에 Access Token이 포함되지 않았을 때 반환됩니다. 유효한 Access Token을 포함해 다시 요청해 주세요.

{
  "detail": {
    "message": "토큰이 만료되었습니다. 새 토큰을 재발급해 세션을 갱신해 주세요."
  }
}

Access Token 포함 요청 예시#

const response = await fetch('http://{{EDGE_IP}}:8100/api/v1/events', {
  method: 'GET',
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
});

const data = await response.json();