인증
FourA API에 대한 모든 request에는 인증이 필요합니다. 이 페이지에서는 API key를 발급받고 사용하며 관리하는 방법을 설명합니다.
API Key 발급받기
- FourA 대시보드에 로그인합니다
- API Keys 페이지로 이동합니다
- Create Key를 클릭합니다
- 확인 대화상자에서 key를 복사합니다
API key는 다음과 같은 형식입니다: pk_live_a1b2c3d4e5f6...
현재 생성되는 key는 다시 확인할 수 있습니다. 나중에 해당 key 행의 눈 아이콘을 클릭하여 전체 secret을 필요할 때 다시 표시할 수 있습니다(확인 절차 및 권한은 API Key 관리 참조). 해당 기능 지원 전에 생성된 레거시 key는 다시 표시할 수 없으며 자물쇠 아이콘이 표시됩니다. 전환하려면 key를 한 번 재생성하십시오.
API Key 사용하기
모든 request의 X-API-Key header에 API key를 포함해야 합니다:
curl -X POST https://eu.api.foura.ai/api/single/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "GET", "url": "https://example.com"}'
Python 사용 시:
import requests
response = requests.post(
"https://eu.api.foura.ai/api/single/",
headers={
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
json={"method": "GET", "url": "https://example.com"}
)
Node.js 환경:
const response = await fetch('https://eu.api.foura.ai/api/single/', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ method: 'GET', url: 'https://example.com' })
});
API Key 보안
API key는 비밀번호처럼 다루어야 합니다.
- 버전 관리 시스템에 커밋하지 마세요. 대신 환경 변수를 사용하세요.
- 클라이언트 측 코드에 노출하지 마세요. 서버 측 애플리케이션에서만 사용하세요.
- 유출된 경우 즉시 교체하세요. Dashboard에서 키를 재생성할 수 있습니다. 기존 보안 키는 1분 이내에 작동을 멈추며, 키 조회 내역은 모두 감사 로그에 기록되므로 탈취된 자격 증명을 사후에 쉽게 파악할 수 있습니다.
환경 변수 사용
키를 환경 변수에 저장하세요.
export FOURA_API_KEY="pk_live_a1b2c3d4e5f6..."
그런 다음 코드에서 이를 참조합니다.
import os
api_key = os.environ["FOURA_API_KEY"]
const apiKey = process.env.FOURA_API_KEY;
일반적인 인증 오류
모든 인증 실패는 401 Unauthorized 상태를 반환합니다.
| 오류 | 메시지 | 원인 | 해결 방법 |
|---|---|---|---|
| 401 | Missing API key. Include X-API-Key header. | request에 X-API-Key header가 없음 |
X-API-Key header 추가 |
| 401 | Invalid API key | 잘못된 키, 불필요한 공백, 또는 비활성화된 키 | 키를 확인하거나, 공백을 제거하거나, Dashboard에서 새 키를 생성 |
데이터베이스 전환 중 등으로 인해 FourA가 일시적으로 키를 확인할 수 없는 경우, 401가 아닌 API key check temporarily unavailable 및 Retry-After: 5와 함께 503로 응답합니다. 해당 대기 시간 후 재시도하십시오. 키 자체에는 문제가 없습니다.
성공과 실패에 관계없이 모든 response에는 X-Foura-Request-Id header가 포함됩니다. 단, FourA가 전혀 읽을 수 없는 body(잘못된 형식의 JSON 또는 100KB 초과 body)는 ID가 할당되기 전에 거부되므로 예외입니다. 지원팀에서 나중에 특정 호출을 조회할 수 있도록 해당 ID를 직접 로깅하십시오.