API Reference

PASSPORT 로그인

인가코드 요청

기본 정보

GET /passport/authorize
HOST : api.maxst.com

Request

Name	Type	Description	Required
client_id	String	PASSPORT 로그인 사용 시 발급된 client id [맥스버스 Console] > [PASSPORT 로그인] > [클라이언트 정보]에서 조회	O
redirect_uri	String	인가 코드 발급 리다이렉트 URI [맥스버스 Console] > [PASSPORT 로그인] > [Redirect URI]에서 등록	O
response_type	String	code 로 고정	O
scope	String	openid, email, name, image [맥스버스 Console] > [PASSPORT 로그인] > [개인정보 제공 동의항목] 에서 등록한 값만 설정 가능	O
code_challenge	String	서버 없이 PKCE 인증방식을 사용할 경우 필요	X
code_challenge_method	String	S256 으로 고정	X

PASSPORT 로그인 동의 화면을 보여준 다음에, 사용자 동의를 받은 경우, 등록해준 redirect uri 로 인가코드를 전달합니다.

동의화면은 사용자가 앱을 최초로 사용할 경우에만 나타납니다. 사용자가 동의항목에 동의를 한 이후부터는 바로 인가코드가 발급되고, 인가코드를 통해 토큰요청을 할 수 있습니다. 토큰에는 사용자가 동의한 항목들에 대한 정보가 포함됩니다.

Redirect Uri

• redirect_uri 인자로 전달하는 값은 [맥스버스 Console] > [PASSPORT 로그인] > [Redirect URI]에서 미리 등록된 값이어야 합니다.

caution

⚠️ 만일 등록되지 않은 redirect_uri 주소로 인가코드가 요청될 경우, 에러가 발생합니다. (문제 해결 링크)

인가코드 발급 성공 시

• code가 쿼리 스트링으로 전달됩니다.
• 해당 code 값으로 토큰을 요청합니다.

인가코드 발급 실패 시

• 에러 정보에 따라, 사용자에게 적절한 안내 문구를 표시하도록 처리합니다.
  • 최초 서비스 가입 시, 사용자 동의에 실패한 경우, redirect_uri로 에러 정보 (error=access_denied)를 담은 쿼리 스트링이 전달됩니다.
  • scope가 없을 경우, redirect_uri로 에러 정보 (error=invalid_scope)를 담은 쿼리 스트링이 전달됩니다.

Request

Name	Type	Description
code	String	인가코드 요청 성공 시, 전달되는 인가코드입니다.
error	String	인가코드 요청 실패 시, 에러 문구입니다.

Sample

Request

https://api.maxst.com/passport/authorize?client_id=${CLIENT_ID}&grant_type=authorization_code&response_type=code&scope=openid name image email&redirect_uri=${REDIRECT_URI}

Response[Success]

GET 302
Location : ${REDIRECT_URI}?code={AUTHORIZATION_CODE}

Response[Failure]

GET 302
Location : ${REDIRECT_URI}?error=access_denied

토큰 요청

기본 정보

POST /passport/token
HOST : api.maxst.com
Content-Type : application/x-www-form-urlencoded

앞에서 발급받은 인가코드로 토큰 발급을 요청합니다. OpenID Connect 를 사용하고 있기 때문에, id token, access token, refresh token이 발급되며 각 토큰에 대한 상세 정보는 토큰 정보에서 확인할 수 있습니다.

Request

Parameter

• client_secret, code_verifier 둘 중 한개의 값은 반드시 필요합니다.

Name	Type	Description	Required
client_id	String	PASSPORT 로그인 사용 시 발급된 client id [맥스버스 Console] > [PASSPORT 로그인] > [클라이언트 정보]에서 조회	O
grant_type	String	authorization_code 로 고정	O
code	String	인가코드 요청에서 발급받은 인가코드	O
redirect_uri	String	인가코드가 redirect 된 URI	O
client_secret	String	토큰 발급 시, 필요한 클라이언트 보안 값	O / X (아래설명참고)
code_verifier	String	client type이 public일 경우, client secret 대신 사용되는 값	X / O (아래설명참고)

• code_verifier 와 client_secret 둘 중 한가지 값은 반드시 필요합니다. client type이 confidential 일 경우, client secret 값을, public 일 경우 code verifier 값을 넣어주세요.
• 단, client secret은 안전한 곳에 보관해두고 사용해야합니다. (Authorization Code Flow vs Authorization Code Flow With PKCE 관련 내용 참고)

Response

Name	Type	Description	Required
access_token	String	사용자의 엑세스 토큰	O
expires_in	Integer	엑세스 토큰, id 토큰의 만료시간(초)	O
refresh_token	String	사용자의 리프레시 토큰	O
refresh_expires_in	Integer	리프레시 토큰 만료 시간(초)	O
token_type	String	Bearer 로 고정	O
id_token	String	사용자의 id 토큰	X
scope	String	토큰에 포함된 scope 정보	O

Sample

Request

• client secret 을 사용할 경우

curl -v -X POST 'https://api.maxst.com/passport/token' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'grant_type=authorization_code' \
 -d 'client_id=${CLIENT_ID}' \
 -d 'redirect_uri=${REDIRECT_URI}' \
 -d 'code=${AUTHORIZATION_CODE}' \
 -d 'client_secret=${CLIENT_SECRET}'

• code verifier 를 사용할 경우

curl -v -X POST 'https://api.maxst.com/passport/token' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'grant_type=authorization_code' \
 -d 'client_id=${CLIENT_ID}' \
 -d 'redirect_uri=${REDIRECT_URI}' \
 -d 'code=${AUTHORIZATION_CODE}' \
 -d 'code_verifier=${CODE_VERIFIER}'

Response

{
    "access_token": ${ACCESS_TOKEN},
    "refresh_token": ${REFRESH_TOKEN},
    "id_token": ${ID_TOKEN},
    "expires_in": 1799,
    "refresh_expires_in": 21599,
    "token_type": "Bearer",
    "scope": ${SCOPE}
}

로그아웃

로그아웃 기능은 PASSPORT 로그인을 통해 생성된 사용자의 세션을 종료하기 위해 사용됩니다. 로그아웃 API가 요청될 경우, PASSPORT로 로그인된 사용자의 세션은 종료되고 이를 통해 발급받은 토큰도 만료됩니다. 로그아웃의 동작 방식은 아래와 같습니다.

Request

POST /passport/connect/logout
HOST api.maxst.com
Content-Type : application/x-www-form-urlencoded

Name	Type	Description	Required
client_id	String	PASSPORT 로그인 사용 시 발급된 client id [맥스버스 Console] > [PASSPORT 로그인] > [클라이언트 정보]에서 조회	O
id_token_hint	String	발급받은 ID 토큰	O

Sample

Request

curl -v -X POST 'https://api.maxst.com/passport/connect/logout' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d ''id_token_hint=${ID_TOKEN}' \
 -d 'client_id=${CLIENT_ID}' \

토큰 갱신

토큰갱신 기능은 엑세스 토큰 만료 시, 발급받은 리프레시 토큰을 통해 유효한 토큰을 발급받기 위해 필요한 과정입니다.

Request

POST /passport/token
HOST api.maxst.com
Content-Type : application/x-www-form-urlencoded

Parameter

Name	Type	Description	Required
client_id	String	PASSPORT 로그인 사용 시 발급된 client id [맥스버스 Console] > [PASSPORT 로그인] > [클라이언트 정보]에서 조회	O
refresh_token	String	발급받은 리프레시 토큰	O
grant_type	String	refresh_token 으로 고정	O
client_secret	String	PASSPORT 로그인 사용 시 발급된 client secret [맥스버스 Console] > [PASSPORT 로그인] > [클라이언트 정보]에서 조회	X

Sample

Request

curl -v -X POST 'https://api.maxst.com/passport/token' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'grant_type=refresh_token' \
 -d 'client_id=${CLIENT_ID}' \
 -d 'client_secret=${CLIENT_SECRET}' \
 -d 'refresh_token=${REFRESH_TOKEN}'

Response

{
    "token": ${ACCESS_TOKEN},
    "refresh_token": ${REFRESH_TOKEN},
    "id_token": ${ID_TOKEN},
    "expires_in": 1799,
    "refresh_expires_in": 21599,
    "token_type": "Bearer",
    "scope": ${SCOPE}
}

서비스에 가입한 유저 목록 조회

해당 애플리케이션 서비스에 가입한 유저의 목록을 조회하는 API 입니다.

Request

GET /profile/v2/biz/application/{application_uuid}/connected/users
HOST api.maxst.com
Content-Type : application/x-www-form-urlencoded

Parameter

Name	Type	Description	Required
application_uuid	String	조회하고자 하는 서비스의 application_uuid	1

Sample

Request

https://api.maxst.com/profile/v2/biz/application/{application_uuid}/connected/users

Response

[
  {
    "profile_uuid": ${profile_uuid},
    "email": ${email},
    "first_name": ${first_name},
    "last_name": ${last_name}
  },
  {
    "profile_uuid": ${profile_uuid},
    "email": ${email},
    "first_name": ${first_name},
    "last_name": ${last_name}
  }
]