OpenAPI

HOME > OpenAPI > OAUTH2.0

OAUTH2.0

공개 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"
    }