인증
Walla Open API 인증 방법
인증
Walla Open API는 API 키 기반 인증을 사용합니다. 모든 API 요청에는 유효한 API 키를 헤더에 포함해야 합니다.
API 키 인증
모든 요청의 X-WALLA-API-KEY 헤더에 API 키를 포함하세요.
헤더 형식
X-WALLA-API-KEY: your_api_key_here팀 범위 API 키
Walla API 키는 팀 단위로 생성됩니다.
- 각 API 키는 특정 팀에 연결됩니다
- 팀 정보는 모든 요청에 자동으로 포함됩니다
- API 호출 시 별도로 팀 정보를 전달하지 않아도 됩니다
- 워크스페이스, 폼, 응답은 자동으로 해당 팀 범위로 필터링됩니다
API 키 발급받기
- app.walla.my에 로그인합니다
- app.walla.my/open-api/doc으로 이동합니다
- 페이지 상단의 API 키 섹션에서 키를 생성하거나 복사합니다
중요: API 키는 비밀번호처럼 안전하게 보관하고, 외부에 공유하지 마세요.
인증된 요청 보내기
각 언어별로 API 키를 포함하는 방법은 다음과 같습니다.
cURL
curl -X GET "https://api.walla.my/open-api/v1/workspaces" \
-H "X-WALLA-API-KEY: your_api_key_here" \
-H "Content-Type: application/json"JavaScript (Fetch)
fetch('https://api.walla.my/open-api/v1/workspaces', {
method: 'GET',
headers: {
'X-WALLA-API-KEY': 'your_api_key_here',
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('오류:', error));Python (requests)
import requests
url = "https://api.walla.my/open-api/v1/workspaces"
headers = {
"X-WALLA-API-KEY": "your_api_key_here",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
data = response.json()
print(data)Node.js (axios)
const axios = require('axios');
const config = {
headers: {
'X-WALLA-API-KEY': 'your_api_key_here',
'Content-Type': 'application/json'
}
};
axios.get('https://api.walla.my/open-api/v1/workspaces', config)
.then(response => console.log(response.data))
.catch(error => console.error('오류:', error));인증 오류
인증에 실패하면 아래와 같은 오류가 반환됩니다.
403 Forbidden
다음 경우에 발생합니다.
- API 키가 유효하지 않거나 만료된 경우
- 해당 리소스에 접근 권한이 없는 경우
- 요청에 API 키가 빠져 있는 경우
응답 예시:
{
"error": "인증 실패 또는 권한 없음"
}모범 사례
보안
- API 키를 커밋하지 마세요 - Git 등 버전 관리 시스템에 API 키를 포함하지 마세요
- 환경 변수를 사용하세요 - API 키는 환경 변수로 관리하세요
- 키를 정기적으로 교체하세요 - 보안을 위해 주기적으로 키를 갱신하세요
- 환경별로 키를 분리하세요 - 개발, 스테이징, 프로덕션 환경에 각각 다른 키를 사용하세요
환경 변수
API 키를 환경 변수에 저장하세요.
# .env 파일
WALLA_API_KEY=your_api_key_here코드에서는 아래와 같이 불러올 수 있습니다.
// JavaScript
const apiKey = process.env.WALLA_API_KEY;# Python
import os
api_key = os.getenv('WALLA_API_KEY')속도 제한
Walla Open API에는 시스템 안정성을 위한 속도 제한이 적용됩니다.
- 제한: API 키당 시간당 6,000건
- 시간 윈도우: 1시간 (롤링 윈도우)
속도 제한을 초과하면 429 Too Many Requests 응답이 반환됩니다. 이 경우:
- 지수 백오프로 재시도하세요
- 가능하면 응답을 캐시하세요
- 불필요한 중복 요청을 줄이세요
- API 사용량을 모니터링하세요
- 가능하면 요청을 일괄 처리하세요
문제 해결
자주 발생하는 문제
문제: API 키를 넣었는데도 403 오류가 발생함
해결 방법:
- API 키가 올바르고 만료되지 않았는지 확인하세요
- 해당 워크스페이스에 대한 권한이 있는지 확인하세요
- 헤더 이름이 정확히
X-WALLA-API-KEY인지 확인하세요 (대소문자 구분) - 접근 권한이 있는 워크스페이스의 리소스인지 확인하세요
문제: API 키가 전달되지 않음
해결 방법:
- 헤더 형식이 올바른지 확인하세요
- HTTP 클라이언트에서 커스텀 헤더가 포함되는지 확인하세요
- 헤더 이름에 오타가 없는지 확인하세요
다음 단계
인증 설정이 끝났다면, 아래 문서를 참고하세요.
추가 보안 고려사항
API 키 보호
-
코드에 하드코딩하지 마세요
- 소스 코드에 API 키를 직접 넣지 마세요
- 환경 변수나 시크릿 관리 서비스를 사용하세요
-
HTTPS만 사용하세요
- API는 HTTPS로만 접근할 수 있습니다
- HTTP 요청은 거부됩니다
-
키 노출 모니터링
- 공개 저장소에 키가 올라가지 않았는지 정기적으로 확인하세요
- 키가 노출된 경우 즉시 폐기하고 새로 발급하세요
권한 관리
- API 키는 워크스페이스 권한과 연결됩니다
- 팀 멤버별로 별도의 API 키를 발급하세요
- 사용하지 않는 키는 바로 폐기하세요
- API 키 사용 현황을 주기적으로 점검하세요
에러 처리 모범 사례
async function makeAuthenticatedRequest(url) {
try {
const response = await fetch(url, {
headers: {
'X-WALLA-API-KEY': process.env.WALLA_API_KEY,
'Content-Type': 'application/json'
}
});
if (response.status === 403) {
console.error('인증 실패: API 키를 확인하세요');
// 사용자에게 알리거나 재인증 프로세스 시작
return null;
}
if (!response.ok) {
throw new Error(`HTTP 오류! 상태: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('요청 실패:', error);
throw error;
}
}import requests
import os
def make_authenticated_request(url):
headers = {
'X-WALLA-API-KEY': os.getenv('WALLA_API_KEY'),
'Content-Type': 'application/json'
}
try:
response = requests.get(url, headers=headers)
if response.status_code == 403:
print('인증 실패: API 키를 확인하세요')
return None
response.raise_for_status()
return response.json()
except requests.RequestException as e:
print(f'요청 실패: {e}')
raise