공개 API의 인증을 위해서 OAuth 2.0 프로토콜 사용을 권장하고 있습니다.

• client_id(회원계정)와 발급받은 client_Secret를 사용하여 서버로 요청하시면, Access_Token을 발급받으실 수 있습니다.
• 발급받은 Access_Token은 API 호출 시, HTTP 헤더에 포함되어야 합니다.
• 만약 제 3자가 고객님의 client_id와 보안키를 획득하면 보안문제가 발생할 수 있습니다. 따라서 Access_Token은 반드시 서버에서 이뤄져야합니다.

1 유효기간

• Access_Token은 1시간, Refresh_Token은 24시간 유효합니다.
• Access_Token이 만료되면, Refresh_Token을 사용하여 재발급이 필요합니다.
• client_id, client_secret 정보로 재발급시 기존 Token은 사용할 수 없습니다.
• API 호출시마다, Access_Token을 새로발급받는 것은 너무 많은 리소스가 사용될 우려가 있습니다.

2 OAuth 2.0의 표준 권한 승인 방법

• (a) 서버(Server)와 클라이언트(Client)사이에 인증을 완료하면 권한 부여의 기능을 수행하는 엑세스 토큰*(Access_Token)을 증표로 전달
• (b) 클라이언트(Clinet)는 이 엑세스 토큰으로 보호된 자원(Protected Resource)에 접근하거나 서비스를 요청할 수 있음
• (c) 자원 서버(Resource Server)는 엑세스 토큰(Access_Token)을 기반으로 권한을 확인 후, 결과를 클라이언트에게 다시 보냄

* 엑세스 토큰(Access Token)

보호된 자원에 접근하거나 서비스를 요청할 때, 클라이언트의 권한을 대표하여 확인용으로 사용함.
엑세스 토큰 하나로 계정 인증에 필요한 모든 것들을 확인할 수 있음

3 API기본정보

• POST방식을 지원합니다.
• 시스템 설정에 따라 GET방식이 가능하나, 보안에 취약하여 권장하지 않습니다.

메서드	인증	요청URL	출력 포맷	설명
POST	OAuth 2.0	https://api.goodapi.co.kr/oauth20/token?returnType=json	json	접근 토큰발급/갱신/삭제 요청
POST	OAuth 2.0	https://api.goodapi.co.kr/oauth20/token?returnType=xml	xml	접근 토큰발급/갱신/삭제 요청

4 요청변수

요청 변수명	타입	필수 여부	기본값	설명
grant_type	string	Y	code	인증 과정에 대한 구분값 1. 발급:'client_credentials' 2. 갱신:'refresh_token' 3. 삭제: 'delete'
client_id	string	Y	-	애플리케이션 등록 시 발급받은 Client ID 값
client_secret	string	Y	-	애플리케이션 등록 시 발급받은 Client secret 값
refresh_token	string	갱신 때 필수	-	사용자 인증에 성공하고 발급받은 갱신 토큰(refresh token)
access_token	string	삭제 때 필수	-	발급받은 접근 토큰으로 URL 인코딩을 적용한 값을 사용
service_provider	string		GSCMS	인증 제공자 이름으로 'GSCMS'로 세팅해 전송

5 출력결과

접근 토근 발급 요청

필드	타입	설명
access_token	string	접근 토큰, 발급 후 expires_in 파라미터에 설정된 시간(초)이 지나면 만료됨
refresh_token	string	접근 토큰의 타입으로 Bearer 지원
expires_in	integer	접근 토큰의 유효 기간(초 단위)
R_CODE	string	결과 코드
R_MSG	string	결과 메시지

접근 토근 갱신 요청

필드	타입	설명
access_token	string	접근 토큰, 발급 후 expires_in 파라미터에 설정된 시간(초)이 지나면 만료됨
token_type	string	접근 토큰의 타입으로 Bearer 지원
expires_in	integer	접근 토큰의 유효 기간(초 단위)
R_CODE	string	결과 코드
R_MSG	string	결과 메시지

접근 토근 삭제 요청

필드	타입	설명
access_token	string	삭제 처리된 접근 토큰 값
result	string	처리 결과가 성공이면 'success'가 리턴
expires_in	integer	접근 토큰의 유효 기간(초 단위)
R_CODE	string	결과 코드
R_MSG	string	결과 메시지

6 OAuth응답코드

OAuth관련 응답코드입니다.

HTTP 코드	결과 코드	결과 메시지	조치 방안
200	0000	정상처리	요청에 대한 정상처리
401	@024	Authentication failed / 인증에 실패했습니다.
401	@028	Authentication header not exists / OAuth 인증 헤더(authorization header)가 없습니다.
403	@403	Forbidden / 호출 권한이 없습니다.	API 요청 헤더에 클라이언트 ID와 Secret 값을 정확히 전송했는지 확인해보시길 바랍니다
404	@404	Not Found / 검색 결과가 없습니다	-
405	@405	HTTP 메서드를 잘못 호출한 경우. POST 방식으로 호출해야 하는데 GET 방식으로 호출한 경우 등입니다	허용하는 HTTP 메서드를 확인합니다.
500	@500	Internal Server Error / 데이터베이스 오류입니다.	서버 내부 에러가 발생하였습니다. 포럼에 올려주시면 신속히 조치하겠습니다.

7 예시

요청 예시

[POST]https://api.goodapi.co.kr/oauth20/token?returnType=json
접근 토큰 발급 요청

{
    "grant_type":"client_credentials"
    "client_id":"jyvqXeaVOVmV"
    "client_secret":"527300A0COq1XV33cf"
    "service_provider":"GSCMS"
}

접근 토큰 갱신 요청

{
    "grant_type":"refresh_token"
    "client_id":"jyvqXeaVOVmV"
    "refresh_token":"vnxzP22RgbQgbNeEMDdD5dSPKGM"
    "service_provider":"GSCMS"
}

접근 토큰 삭제 요청

{
    "grant_type":"delete"
    "client_id":"jyvqXeaVOVmV"
    "access_token":"d30C9mWef2g5H1Y4QjVQzFWzG8vMsQwIaC1fmYxHyI"
    "service_provider":"GSCMS"
}

응답 예시

접근 토큰 발급 요청

{
    "access_token":"d30C9mWef2g5H1Y4QjVQzFWzG8vMsQwIaC1fmYxHyI",
    "refresh_token":"vnxzP22RgbQgbNeEMDdD5dSPKGM",
    "token_type":"bearer",
    "expires_in":"3600"
}

접근 토큰 갱신 요청

{
    "access_token":"wGijpi0NkhQfoR8CB46xkUxAUtcpACQEtfQROn3QTx4",
    "token_type":"bearer",
    "expires_in":"3600"
}

접근 토큰 삭제 요청

{
    "access_token":"d30C9mWef2g5H1Y4QjVQzFWzG8vMsQwIaC1fmYxHyI",
    "result":"success"
}