Auth Token(인증 토큰) 발행 — BizSpring AIR™ API
핵심 요약
- Growth Platform™ API 사용 전 인증 토큰을 발행받는 방법을 설명한다.
- https://growthplatform.ai/auth/signin 에 username, password를 JSON으로 POST하여 토큰을 발급받는다.
- 발급된 토큰은 API 요청 헤더에 Authorization: Bearer {ACCESS_TOKEN} 형태로 포함해야 한다.
- 응답 결과에는 token_type(Bearer 고정)과 만료 기간이 있는 token 값이 포함된다.
- 400/401/403/429 등 오류 코드와 각 상황(파라미터 누락, 인증 오류, 권한 없음, 요청 한도 초과)이 정의되어 있다.
# Auth Token(인증 토큰) 발행
인증 토큰 발행하기
인증 토큰은 Growth Platform™ API를 사용하기 위해 먼저 발행해야 하는 항목입니다.
- 토큰은 API 요청을 보낼 때 클라이언트를 인증하는데 사용되며, 각 요청 시 헤더에 포함되어야 합니다.
- 요청 성공 시 응답은 토큰과 토큰 정보를 포함합니다.
> API 사용을 위해서는 활성화된 API 사용 권한을 보유한 Growth Platform™ 계정이 필요합니다.
>
> 계정 생성 또는 API 사용 권한이 있는지 확인이 필요한 경우 growth-platform-tm을 참고합니다.
인증 방식
모든 API 요청 헤더에 포함:
http
Authorization: Bearer {ACCESS_TOKEN}요청 URL
아래 요청 URL로 계정 정보를 함께 요청하는 것으로서 인증 토큰을 발행 받고 획득하게 됩니다.
**https://growthplatform.ai/auth/signin
**
프로토콜
HTTPS
HTTP 메서드
POST
Request Body
Request Body를 JSON 형식으로 전달(요청) 합니다.
| 키 | 타입 | 설명 |
|---|---|---|
| username | string | 사용자 계정의 고유 아이디를 의미합니다. |
| password | string | 사용자 계정의 고유 비밀번호를 의미합니다. |
요청 예
POST /auth/signin
HEADER
Content-Type: application/json
BODY
{
"username": "{ADMIN_ID}",
"password": "{ADMIN_PW}"
}
# JavaScript JQuery
const sendData = {
'username': "{username}",
'password': "{password}"
};
let token;
$.ajax({
url: 'https://growthplatform.ai/auth/signin',
method: 'POST',
contentType: 'application/json; charset=utf-8',
data: JSON.stringify(sendData),
success: function (data) {
// success
token = data.token;
},
error: function (error) {
// error
}
});응답 결과 데이터
응답에 성공하면 JSON 형식으로 결과값이 반환됩니다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
| token_type | string | 발행된 토큰의 타입. Bearer 로 고정 |
| token | string | 리포트 데이터 요청 시 사용되는 만료 기간이 있는 토큰 |
응답 예
**HTTP/1.1 200 OK
**Content-Type: application/json;charset=UTF-8
**{
** "token_type": "Bearer",
"token": "eyJraWQiOiI0ZGE2YmYxNy0wYTZmL....SrYiSAX7lZhc-rxKbrooQ8KQ-Dq7CV1tA"
}
> HTTP Request에 대한 200 OK 응답이 아닌 경우는 username 및 password의 오류가 아닌, 클라이언트-API서버와의 통신문제이거나 기타 문제입니다.
>
> 이 경우에는 HTTP 표준 응답 코드를 참고하시기 바랍니다.
오류 코드
| HTTP | 오류 코드 | 설명 |
|---|---|---|
| 400 | invalid\_request | 필수 파라미터 누락 |
| 401 | invalid\_client | client\_id/secret 오류 |
| 403 | access\_denied | 접근 권한 없음 |
| 429 | too\_many\_requests | 요청 한도 초과 |
***
추가 예시
토큰 발행 — cURL
curl -X POST https://api.bizspring.co.kr/air/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"grant_type": "client_credentials"
}'import requests
def get_access_token(client_id: str, client_secret: str) -> str:
url = "https://api.bizspring.co.kr/air/v1/auth/token"
payload = {
"client_id": client_id,
"client_secret": client_secret,
"grant_type": "client_credentials"
}
response = requests.post(url, json=payload)
response.raise_for_status()
return response.json()["access_token"]
token = get_access_token("your_client_id", "your_client_secret")async function getAccessToken(clientId, clientSecret) {
const response = await axios.post(
'https://api.bizspring.co.kr/air/v1/auth/token',
{ client_id: clientId, client_secret: clientSecret, grant_type: 'client_credentials' }
);
return response.data.access_token;
}응답 예시
json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}자주 묻는 질문
API를 사용하려면 뭐가 먼저 필요한가요?
먼저 Growth Platform™ API 사용을 위한 인증 토큰을 발행받아야 합니다. 이를 위해서는 활성화된 API 사용 권한을 보유한 Growth Platform™ 계정이 필요합니다.
토큰은 어떻게 발급받나요?
https://growthplatform.ai/auth/signin 으로 username과 password를 JSON 형식의 Request Body에 담아 POST 요청을 보내면 됩니다. 요청이 성공하면 token_type과 token 값이 담긴 JSON 응답을 받습니다.
발급받은 토큰은 어떻게 사용하나요?
모든 API 요청의 헤더에 Authorization: Bearer {ACCESS_TOKEN} 형태로 포함시켜야 합니다.
요청이 200 OK로 안 오면 아이디/비밀번호가 틀린 건가요?
아닙니다. 200 OK가 아닌 응답은 username/password 오류가 아니라 클라이언트-API서버 간 통신 문제이거나 기타 문제일 수 있습니다. 이 경우 HTTP 표준 응답 코드를 참고해야 합니다.
오류가 나면 어떤 코드들을 확인해야 하나요?
400 invalid_request(필수 파라미터 누락), 401 invalid_client(client_id/secret 오류), 403 access_denied(접근 권한 없음), 429 too_many_requests(요청 한도 초과)가 정의되어 있습니다.