API 접속과 인증

광고·추천 요청과 이벤트·로그 전송에는 액세스 토큰이 필요 없습니다. 광고 운영 데이터를 관리하는 API를 호출할 때만 액세스 토큰을 발급해 사용합니다. 광고를 요청하고 표시한 뒤 클릭 이벤트 수집까지 확인하려면 Quick Start를 따라 진행하세요. 광고 요청과 이벤트 전송만 사용하는 경우에는 토큰 발급 단계를 건너뛸 수 있습니다.

API 주소

A2 On-Premise와 A2 Cloud 모두 배포 환경에서 제공받은 API 접속 주소를 사용합니다. 예시의 your_a2_service를 해당 환경의 도메인으로 바꿔 사용하세요.

https://your_a2_service

상태 확인 API로 주소가 올바른지 확인할 수 있습니다.

curl "https://your_a2_service/api/manager/health"

Response

{"plane": "manager", "status": "ok", "db": "connected"}

API별 인증

호출하는 API의 용도에 따라 액세스 토큰이 필요한지가 다릅니다.

용도	API	액세스 토큰
광고·추천 요청, 노출·클릭·전환 등 광고 이벤트와 사용자 행동 로그 전송	Decision API	불필요
광고주, 캠페인, 소재, 지면, 카탈로그 등 광고 운영 데이터 관리	Data Management API	필요

광고·추천 요청과 이벤트·행동 로그 전송 API는 액세스 토큰 없이 호출하므로 웹이나 앱에서 직접 호출할 수 있습니다. Data Management API는 Authorization: Bearer <token> 헤더에 액세스 토큰을 넣어 서버에서 호출합니다.

웹이나 앱 코드에 토큰을 포함하면 외부에 노출될 수 있습니다.

액세스 토큰 발급

액세스 토큰은 관리자 계정으로 Ad Manager에서 발급합니다.

Ad Manager 로그인

관리자 계정으로 Ad Manager에 로그인합니다.

개발 설정으로 이동

관리 > 설정 메뉴의 개발 설정 영역으로 이동합니다.

토큰 발급 또는 복사

액세스 토큰이 비어 있다면 새로고침 아이콘을 눌러 발급합니다. 이미 발급된 토큰이 있다면 복사 아이콘을 눌러 복사합니다. 새로고침 아이콘을 누르면 기존 토큰은 더 이상 사용할 수 없으니 주의하세요.

테스트용 로그인 토큰 발급하기

계정 이메일과 비밀번호로 로그인 토큰을 발급할 수도 있습니다. 로그인 토큰은 발급한 계정의 권한으로 동작하며, 8시간이 지나면 만료됩니다. 테스트나 일시적인 작업에 사용하세요.응답의 access_token 값이 로그인 토큰이며, 개발 설정에서 발급하는 액세스 토큰과는 다른 토큰입니다.

curl -X POST "https://your_a2_service/api/auth/jwt/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=dev@example.com" \
  --data-urlencode "password=<비밀번호>"

Response

{"access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "bearer"}

토큰으로 API 호출하기

<token> 자리에 발급한 토큰을 넣고 내 계정 정보를 조회해 인증이 정상적으로 동작하는지 확인합니다.

curl "https://your_a2_service/api/users/me" \
  -H "Authorization: Bearer <token>"

인증에 성공하면 토큰을 발급한 계정의 정보가 반환됩니다.

Response (일부)

{
  "id": "3f6c2a1e-8b7d-4c1a-9e2f-5d4b3a2c1b0a",
  "email": "a2-integration@example.com",
  "role": "admin",
  "is_active": true
}

토큰이 없거나 유효하지 않으면 401, 계정에 해당 API를 호출할 권한이 없으면 403이 반환됩니다.

토큰 재발급

액세스 토큰은 만료 기한을 따로 관리할 필요가 없으며, 시스템에 하나만 존재합니다. 토큰이 유출되었거나 교체가 필요하면 Ad Manager의 개발 설정 화면에서 재발급하세요. 액세스 토큰은 발급한 관리자 계정의 권한으로 동작합니다. 발급한 계정을 비활성화하거나 삭제하면 해당 토큰을 사용하는 요청이 실패하고, 계정의 역할이나 권한을 바꾸면 일부 API를 호출하지 못할 수 있습니다. 계정을 정리하거나 권한을 바꾸기 전에 다른 관리자 계정으로 토큰을 재발급해 연동 시스템에 반영하세요. API로 재발급할 수도 있습니다. 새 토큰은 응답의 access_token.access_token 값으로 확인합니다.

재발급하면 기존 토큰은 바로 사용할 수 없습니다. 기존 토큰을 사용하던 시스템에 새 토큰을 반영하세요.

curl -X POST "https://your_a2_service/api/manager/settings/access-token" \
  -H "Authorization: Bearer <token>"

시작하기

연동 가이드

API 주소

API별 인증

액세스 토큰 발급

토큰으로 API 호출하기

토큰 재발급

​API 주소

​API별 인증

​액세스 토큰 발급

​토큰으로 API 호출하기

​토큰 재발급

API 주소

API별 인증

액세스 토큰 발급

토큰으로 API 호출하기

토큰 재발급