Skip to main content

개요

FIM One API는 두 가지 인증 방법을 지원합니다:
  1. API 키 — 서비스 간 통합을 위한 간단한 장기 토큰
  2. JWT 토큰 — 사용자 로그인의 단기 토큰 (SSE 엔드포인트용)
대부분의 통합은 API 키를 사용해야 합니다.

API 키

API 키는 사용자 계정에 연결된 장기 자격 증명입니다. 다음과 같은 경우에 이상적입니다:
  • 서버 간 통합
  • 예약된 스크립트 및 자동화
  • FIM One에 액세스하는 외부 애플리케이션

API 키 생성

  1. FIM One 포털에 로그인
  2. 설정 → API 키로 이동
  3. API 키 생성 클릭
  4. 이름 입력 (예: “Production Integration”)
  5. (선택사항) 액세스를 제한하기 위해 범위 설정
  6. (선택사항) 만료 날짜 설정
  7. 생성 클릭
  8. 키를 즉시 복사 — 한 번만 표시됨
전체 키는 다음과 같습니다: fim_your44characterkeystringhere (fim_ 접두사로 시작)

API 키 사용

Authorization 헤더에 Bearer 토큰으로 키를 포함하세요:
또는 Python에서:

API 키 기능

가시성: 각 키는 다음을 표시합니다:
  • 키 접두사 (식별을 위한 처음 8자)
  • 생성 날짜
  • 마지막 사용 타임스탬프
  • 총 요청 수
  • 활성 상태
  • 만료 날짜 (설정된 경우)
관리: 다음을 수행할 수 있습니다:
  • 키를 삭제하지 않고 활성화/비활성화
  • 자동 만료 날짜 설정
  • 키 영구 삭제
  • 사용 패턴 추적

범위

범위는 API 키가 액세스할 수 있는 항목을 제한합니다. 범위를 설정하지 않으면 키는 전체 액세스 권한을 가집니다. 사용 가능한 범위: 범위를 사용하여 키 생성:

JWT 토큰

JWT 토큰은 단기 유효하며 로그인 시 발급됩니다. 다음 용도로 사용됩니다:
  • SSE 스트리밍 엔드포인트: /api/react/api/dag에 대한 요청 본문에 토큰 전달
  • 포털 세션: 프론트엔드 인증

JWT 토큰 가져오기

JWT 토큰은 웹 포털을 통해 로그인하거나 인증 엔드포인트를 호출할 때 자동으로 발급됩니다:
응답:

JWT를 사용한 스트리밍

SSE 엔드포인트의 경우 요청 본문에 토큰을 포함하세요:
또는 읽기 가능한 스트림을 사용하는 JavaScript의 fetch에서 (엔드포인트는 POST 전용이므로 GET만 지원하는 기본 EventSource는 사용할 수 없습니다):

토큰 새로고침

액세스 토큰은 2시간 후에 만료됩니다. 새로고침 토큰을 사용하여 다시 로그인하지 않고 새 액세스 토큰을 얻을 수 있습니다:

보안 모범 사례

API 키

API 키를 버전 관리에 커밋하지 마세요. API 키는 데이터에 대한 전체 액세스 권한을 제공합니다.
  1. 환경 변수에 저장:
    그런 다음 코드에서 참조:
  2. 키 로테이션 사용:
    • 새 키 생성
    • 애플리케이션 업데이트
    • 이전 키 삭제
    • 분기별로 반복
  3. 만료 날짜 설정:
    • 임시 통합에는 단기 키 사용
    • 주기적으로 재인증 필요
  4. 범위가 지정된 키 사용:
    • 필요한 경우가 아니면 “전체 액세스” 키 사용 금지
    • 다양한 서비스에 대해 별도의 키 생성
    • 키가 손상된 경우 피해 제한
  5. 사용량 모니터링:
    • “마지막 사용” 타임스탬프 확인
    • 요청 수 검토
    • 사용하지 않는 키 삭제

JWT 토큰

  1. 수명을 짧게 유지: 액세스 토큰은 2시간 후 만료됨
  2. 안전한 저장:
    • 브라우저에서: HttpOnly 쿠키 사용 (localStorage보다 안전함)
    • 서버에서: 안전한 세션 저장소 사용
  3. 로그에 노출하지 않기: 전체 토큰이 아닌 토큰 접두사만 로깅
  4. HTTPS만 사용: 암호화되지 않은 연결을 통해 토큰을 전송하지 않기

속도 제한

키별 속도 제한은 향후 릴리스에서 계획되어 있습니다. 현재는 적용되는 키별 요청 제한이 없습니다.

문제 해결

유효하지 않은 토큰 오류

원인:
  • API 키 접두사가 잘못됨 (fim_으로 시작해야 함)
  • JWT 토큰이 만료됨 (새로고침 필요)
  • 토큰이 형식이 잘못되었거나 손상됨
  • API 키가 삭제됨
해결 방법: 토큰 형식을 확인하고 필요한 경우 다시 생성하세요

인증 오류

원인:
  • Authorization 헤더가 제공되지 않음
  • 요청 본문에 토큰이 없음 (SSE 엔드포인트의 경우)
  • API 키가 비활성화됨
해결책: 모든 요청에 유효한 토큰을 포함하세요

Forbidden 오류

원인:
  • API 키가 범위가 지정된 액세스 권한을 가지고 있으며 필요한 범위가 없음
  • 사용자 계정에 제한된 권한이 있음
해결책: 적절한 범위를 가진 키를 사용하거나 키 권한을 증가시키세요

만료된 토큰

해결책: 새로운 액세스 토큰을 얻기 위해 새로고침 토큰을 사용하세요:

환경 변수 설정

Python

Node.js

Bash

지원

인증 문제의 경우:
  • 응답 형식 세부 정보는 API 개요를 확인하세요
  • GET /api/auth/verify로 토큰 만료를 검토하세요
  • 키가 손상되었다고 생각되면 지원팀에 문의하세요