인증
모든 Gateway 호출은 Letsur Gateway 키로 인증합니다. 헤더를 붙이는 방식은 호출하는 경로에 따라 두 가지로 갈립니다. OpenAI 호환 경로는 Authorization: Bearer 를, Anthropic 네이티브 경로는 x-api-key 를 씁니다.
두 가지 인증 방식
| 경로 | base URL | 인증 헤더 | 추가 헤더 |
|---|---|---|---|
OpenAI 호환 (/v1/chat/completions·/v1/responses·/v1/embeddings·/v1/models) | https://gw.letsur.ai/v1 | Authorization: Bearer <API_KEY> | Content-Type: application/json |
Anthropic 네이티브 (/v1/messages) | https://gw.letsur.ai | x-api-key: <API_KEY> | anthropic-version: 2023-06-01, Content-Type: application/json |
base URL은 경로마다 다릅니다. OpenAI 호환은 /v1 까지 포함하지만, Anthropic 네이티브는 /v1 없이 루트(https://gw.letsur.ai)만 씁니다. Anthropic SDK가 /v1/messages 를 내부에서 붙이므로, base URL에 /v1 을 또 넣으면 /v1/v1/messages 가 되어 호출이 실패합니다.
OpenAI 호환 — Bearer 토큰
가장 많이 쓰는 방식입니다. Authorization 헤더에 키를 Bearer <API_KEY> 형태로 담아 보냅니다.
cURL
curl https://gw.letsur.ai/v1/chat/completions \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"messages": [{"role": "user", "content": "안녕하세요"}]
}'Anthropic 네이티브 — x-api-key
/v1/messages 경로는 Anthropic 표준 헤더를 씁니다. x-api-key 에 Gateway 키를, anthropic-version 에 API 버전을 담아 보냅니다.
cURL
curl https://gw.letsur.ai/v1/messages \
-H "x-api-key: <API_KEY>" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "안녕하세요"}]
}'SDK를 쓰면 x-api-key 와 anthropic-version 헤더가 자동으로 붙습니다. curl 로 직접 호출할 때만 두 헤더를 명시합니다.
키 발급과 보관
키는 Space의 AI Gateway 안 키 탭에서 발급합니다. 키는 발급 직후 한 번만 보이므로, 그때 바로 안전한 곳에 보관합니다.
키를 코드·깃 저장소·클라이언트(브라우저, 모바일 앱)에 그대로 넣지 마세요. 키가 노출되면 누구나 호출해 비용을 발생시킬 수 있습니다. 키는 환경 변수나 비밀 관리 도구에 보관하고, 노출됐다면 즉시 폐기하고 새로 발급합니다.
키 발급·폐기·만료 같은 운영은 키 라이프사이클에서 다룹니다. 키마다 월 한도를 거는 기준은 한도 개요에서 확인합니다.
인증 실패
키가 없거나 만료·폐기됐으면 401을 반환합니다. 에러 응답도 RFC 7807 형식을 따릅니다.
{
"type": "api_key_not_found",
"title": "Api Key Not Found",
"status": 401,
"detail": "API key not found or has been revoked",
"error_ref": "err_a3f2c1d8e5b0"
}| 상태 | type | 언제 | 해결 |
|---|---|---|---|
| 401 | api_key_not_found | 키가 없거나 폐기됨 | 키 확인 또는 새로 발급 |
| 401 | api_key_revoked | 폐기된 키 | 새 키 발급 (키 라이프사이클) |
| 401 | api_key_expired | 만료된 키 | 새 키 발급 |
공통 에러는 에러 코드에서 모두 확인할 수 있습니다.
자주 묻는 질문
Q. 키를 잃어버렸는데 어떻게 하나요? A. 키는 발급 직후 한 번만 보이고 다시 볼 수 없습니다. 새 키를 발급합니다.
Q. Authorization 과 x-api-key 중 무엇을 써야 하나요?
A. 호출하는 경로에 따라 정해집니다. /v1/messages(Anthropic 네이티브)만 x-api-key 를 쓰고, 나머지 OpenAI 호환 경로는 Authorization: Bearer 를 씁니다.