인증 & 저지연 호출 구조
precheck 직접 호출과 서버 프록시, 단기 JWT 발급, CORS 등 저지연 호출 구조를 설명합니다.
촬영 플로우를 최저 지연으로 엮되 API 키는 감추는 호출 구조를 설명합니다.
두 가지 호출을 나눠서 다룬다
| 호출 | 성격 | 지연 민감도 | 권장 경로 |
|---|---|---|---|
| precheck | 싸고 빠름 (게이트만) | 매우 높음 | 클라이언트 → AI Engine 직접(바이트) |
| 정식 분석 | 비쌈 (측정·OCR), 과금·영속화 | 낮음 (이미 다음 타이어 촬영 중) | 서버측 비동기 (Report API가 트리거) |
핵심: 지연에 민감한 precheck만 클라이언트에서 엔진을 직접 호출해 왕복을 줄이고, 비싼 정식 분석은 서버측 비동기로 남깁니다. 브라우저가 정식 분석을 직접 부르지 않습니다.
API 키는 브라우저에 두지 않는다
시작하기에서 안내하듯, API 키는 서버 전용입니다(브라우저·모바일앱에 노출 금지). 그래서 클라이언트가 엔진을 직접 부를 때는 키가 아니라 수명이 짧은 JWT만 넘깁니다.
단기 토큰 발급
자사 백엔드에서(키를 보유한 곳) AI Engine의 토큰 엔드포인트로 단기 JWT를 발급받아, 토큰만 클라이언트에 내려줍니다.
curl -X POST https://api.atrace.ai/v2/auth/token \
-H "Authorization: Bearer $ATRACE_AI_KEY" \
-H "Content-Type: application/json" \
-d '{ "expiration_duration": 300 }'
# → { "token": "<JWT>" }expiration_duration은 초 단위이며 최대 7200(2시간)입니다. 브라우저용은 짧게(예: 300초 이하) 발급하세요.- 발급받은 JWT를
Authorization: Bearer <JWT>로 실어 precheck를 호출합니다.
발급용 키는 precheck 전용 스코프를 권장
토큰은 발급에 쓴 키의 권한을 그대로 물려받습니다. 그래서 브라우저용 토큰은 ai:precheck 스코프 키로 발급하는 것을
권장합니다 — 토큰이 탈취돼도 precheck만 가능하고 비싼 정식 분석은 불가합니다. 서버측 정식 분석에 쓰는 키(ai:*)와
분리해 발급하세요. 스코프 설정이 필요하면 오토피디아에 문의하세요.
두 가지 패턴
| 패턴 P — 프록시 | 패턴 D — 직접 + 단기 JWT | |
|---|---|---|
| 경로 | 클라이언트 → 자사 백엔드 → 엔진 | 클라이언트 → 엔진 직접 |
| 지연 | 홉 1개 추가 | 최저 |
| 키/토큰 노출 | 자사 서버에만 | 브라우저에 단기 JWT |
| CORS | 불필요 | 필요 (아래) |
| 적합 | 키를 어디에도 안 내보내고 싶을 때 | 최저 지연이 필요할 때 |
두 패턴 모두 유효합니다. 최저 지연이 목표면 패턴 D를, 단순·보수적으로 가려면 패턴 P를 쓰세요.
클라이언트 통합 규약 (권장)
아래 습관대로 구현하면, 오토피디아가 나중에 보안을 강화(토큰 수명 단축·스코프 제한·호출 제한 추가)해도 클라이언트 코드를 고칠 필요가 없습니다.
토큰은 불투명하게 취급 — 내용(claim)을 파싱하거나 유효기간을 가정하지 말고, 백엔드가 준 문자열을 그대로 사용합니다.
401(만료)이면 자사 백엔드에서 재발급 — 토큰 수명이 짧아져도 자동으로 대응됩니다.
429(호출 제한)이면 백오프 후 재시도 — 나중에 호출 제한을 걸어도 깨지지 않습니다.
토큰은 precheck에만, 촬영 세션 단위로 발급 — 정식 분석은 서버측에서 처리합니다.
CORS (패턴 D)
브라우저에서 AI Engine을 직접 호출하려면, 자사 웹 도메인(origin)이 게이트웨이에 허용 등록되어 있어야 합니다. 허용할 도메인은 프로젝트 콘솔의 [CORS 도메인] 탭에서 직접 등록·삭제합니다 (프로젝트당 최대 20개). 변경은 최대 ~1분 후 적용됩니다. 서버측 호출(패턴 P)은 CORS와 무관합니다.
CORS 에러 vs 401 — 구분해서 디버깅
게이트웨이가 CORS를 처리하므로 두 가지를 구분할 수 있습니다.
- 등록 안 된 origin에서 호출 → 응답에 허용 헤더가 없어 브라우저가 CORS로 차단합니다(
Failed to fetch). → 해당 도메인을 등록하세요. - 등록된 origin + 만료·잘못된 토큰 →
401이 정상적으로 돌아옵니다(CORS 에러 아님). 게이트웨이가 인증 실패 응답에도 CORS 헤더를 붙이므로 브라우저가401을 읽을 수 있습니다. → 토큰을 재발급하세요.
즉 "CORS 에러"가 뜨면 origin 등록을, 401 이 뜨면 토큰을 의심하세요.
precheck 통과 후 — 업로드 + 분석
precheck가 analyzable: true를 반환하면 그때 이미지를 스토리지에 올리고 분석을 시작합니다.
업로드 — 자사 스토리지의 불변 URL을 쓰거나(모드 A), ATRACE Pre-Signed 업로드(모드 B)를 씁니다. 자세한 내용은 이미지 수집을 참고하세요.
요약
- precheck: 클라이언트 → 엔진 직접(단기 JWT + 바이트), 발급 키는
ai:precheck권장. - 정식 분석: 서버측 비동기(Report API가 트리거), 완료는 웹훅/폴링.
- API 키: 서버 전용. 브라우저에는 수명이 짧은 JWT만 내려갑니다.