OAuth API
Imweb OAuth API
아임웹 연동 OAuth API
Imweb OAuth API
아임웹 쇼핑몰 연동을 위한 OAuth API입니다.
Base URL: /ai/imweb/oauth
인증 정보
| 항목 | 값 |
|---|---|
| 인증 필요 | 아니오 (OAuth 플로우) |
| 인증 방식 | JWT State Token |
엔드포인트 목록
| 메서드 | 경로 | 설명 | 인증 |
|---|---|---|---|
GET | /ai/imweb/oauth/entry | 아임웹 서비스 진입점 | 불필요 |
GET | /ai/imweb/oauth/authorize | 인가 URL 생성 | State Token |
GET | /ai/imweb/oauth/callback | 인가 콜백 | State Token |
POST | /ai/imweb/oauth/refresh | 토큰 갱신 | 불필요 |
API 상세
아임웹 서비스 진입점
아임웹에서 앱 설치 시 호출되는 진입점입니다. 회원가입 페이지로 리다이렉트됩니다.
이 엔드포인트는 아임웹 "서비스 URL"로 등록되어 있습니다.
HTTP 요청
GET /ai/imweb/oauth/entry?siteCode={siteCode}Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
siteCode | string | 예 | 아임웹 사이트 코드 |
응답
회원가입 페이지로 리다이렉트됩니다. ctx 파라미터에 JWT가 포함됩니다.
인가 URL 생성
아임웹 OAuth 인가 URL을 생성합니다.
HTTP 요청
GET /ai/imweb/oauth/authorize?ctx={ctx}&userId={userId}Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
ctx | string | 예 | entry에서 받은 JWT context |
userId | string | 예 | 가입한 사용자 ID |
응답
성공 응답 (200 OK)
https://openapi.imweb.me/oauth2/authorize?responseType=code&clientId=...&redirectUri=...&scope=site-info:read%20site-info:write&state=...&siteCode=...아임웹 인가 페이지 URL을 반환합니다.
에러 응답 (401 Unauthorized)
Invalid ctxctx JWT가 유효하지 않거나 만료된 경우입니다.
인가 콜백
아임웹 OAuth 인가 완료 후 콜백입니다.
이 엔드포인트는 아임웹에서 자동으로 호출됩니다. 직접 호출하지 마세요.
HTTP 요청
GET /ai/imweb/oauth/callback?code={code}&state={state}Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
code | string | 예 | 아임웹 인가 코드 |
state | string | 아니오 | JWT State Token |
errorCode | string | 아니오 | 에러 코드 (실패 시) |
message | string | 아니오 | 에러 메시지 (실패 시) |
응답
성공/실패 모두 프론트 메인 페이지로 리다이렉트됩니다.
토큰 갱신
아임웹 Access Token을 갱신합니다.
HTTP 요청
POST /ai/imweb/oauth/refresh?refreshToken={refreshToken}Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
refreshToken | string | 예 | 아임웹 Refresh Token |
응답
성공 응답 (200 OK)
{
"accessToken": "...",
"refreshToken": "...",
"tokenType": "Bearer",
"expiresIn": 3600,
"scope": "site-info:read site-info:write"
}에러 응답 (400 Bad Request)
{
"errorCode": "missing_refresh_token",
"message": "Refresh Token이 제공되지 않았습니다."
}에러 응답 (401 Unauthorized)
{
"errorCode": "30101",
"message": "Refresh Token이 만료되었습니다."
}에러 코드
| 코드 | 설명 |
|---|---|
30101 | Refresh Token 만료 |
30102 | Refresh Token 무효 |
missing_refresh_token | Refresh Token 누락 |
missing_code | 인가 코드 누락 |
OAuth 플로우
1. 아임웹 앱 설치 → GET /entry?siteCode=...
2. 서버 → 회원가입 페이지로 리다이렉트 (ctx JWT 포함)
3. 사용자 회원가입 완료 후 → GET /authorize?ctx=...&userId=...
4. 서버 → 아임웹 인가 URL 반환
5. 프론트 → 아임웹 인가 페이지로 이동
6. 사용자 → 권한 허용
7. 아임웹 → GET /callback?code=...&state=...
8. 서버 → Access Token 교환 → 연동 완료
9. 서버 → 프론트 메인 페이지로 리다이렉트JWT State Token
아임웹 OAuth 플로우에서 CSRF 공격 방지 및 상태 유지를 위해 JWT State Token을 사용합니다.
ctx Token (entry → authorize)
| 클레임 | 설명 |
|---|---|
sc | 사이트 코드 |
iss | 발급자 (glowb-api) |
aud | 수신자 (imweb-ctx) |
iat | 발급 시각 |
exp | 만료 시각 (20분) |
jti | 토큰 고유 ID |
state Token (authorize → callback)
| 클레임 | 설명 |
|---|---|
sc | 사이트 코드 |
uid | 사용자 ID |
ru | 리턴 URL |
iss | 발급자 (glowb-api) |
aud | 수신자 (imweb-authorize) |
iat | 발급 시각 |
exp | 만료 시각 (20분) |
jti | 토큰 고유 ID |