API 레퍼런스

OAuth 엔드포인트를 포함해 놀아 계정이 제공하는 API 요청/응답 스펙 레퍼런스입니다.

놀아 계정이 제공하는 엔드포인트 4개입니다. 모든 예시는 이 서버 기준(https://account.nola.kr)으로 적혀 있습니다.

GET `/oauth/authorize`

사용자를 로그인·동의 화면으로 보냅니다. 서버 API가 아니라 브라우저를 이동시키는 주소입니다.

파라미터	필수	값
`response_type`	필수	`code` 고정
`client_id`	필수	마이페이지에서 발급받은 값
`redirect_uri`	필수	등록된 콜백과 완전히 동일해야 함
`scope`	필수	공백 구분. 비우면 `invalid_scope`
`state`	필수	CSRF 방지용 난수. 빠지면 `invalid_request`
`code_challenge`	필수	PKCE. 빠지면 `pkce_required`
`code_challenge_method`	권장	`S256`만 허용. 생략 시 `S256`으로 간주
`ui_locales`	선택	로그인·동의 화면 언어. `ko`·`en`·`vi`. 공백으로 여러 개 가능. 사용자가 직접 고른 언어가 있으면 그쪽이 우선. 인증 판단에는 영향 없음

성공하면 콜백 주소로 ?code=...&state=...가 붙어 돌아옵니다. 인증 코드는 10분 유효 · 1회용입니다.

POST `/oauth/token`

application/x-www-form-urlencoded로 보냅니다. 반드시 서버에서 호출하세요 — client_secret이 들어갑니다.

인증 코드 교환

curl -X POST https://account.nola.kr/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=RECEIVED_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=SAVED_VERIFIER"

토큰 갱신

curl -X POST https://account.nola.kr/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=SAVED_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

응답 (양쪽 공통)

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "profile.avatar profile.basic"
}

갱신하면 refresh_token도 새로 발급되고 기존 것은 폐기됩니다(로테이션). 응답에 담긴 새 refresh_token을 반드시 저장하세요. 옛 값을 계속 쓰면 다음 갱신에서 실패합니다.

수명	기본값
access_token	1시간 (`expires_in` 참고)
refresh_token	30일
인증 코드	10분 · 1회용

GET `/oauth/userinfo`

curl https://account.nola.kr/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "sub": "pws_xxxxxxxxxxxxxxxx",
  "nickname": "놀아유저",
  "scope": "profile.avatar profile.basic service.member_email.read",
  "profile_image_url": "https://…/uploads/…jpg",
  "email": "user@example.com"
}

profile_image_url은 profile.avatar가 있을 때만 나오고, 사진이 없으면 null입니다. email은 스코프 레퍼런스의 조건을 만족할 때만 나옵니다.

sub는 서비스마다 다릅니다(pairwise). 같은 사람이라도 다른 서비스에서는 다른 값이 나갑니다. 사용자 식별 키로는 쓰되, 서비스 간 대조용으로는 쓸 수 없습니다.

GET `/oauth/domain-info`

service.domain.read 스코프 전용입니다. 사용자가 등록한 서비스 목록을 반환합니다.

curl https://account.nola.kr/oauth/domain-info \
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "sub": "pws_…",
  "scope": "profile.basic service.domain.read",
  "services": [
    { "name": "…", "description": "…", "domain": "https://…",
      "status": "active", "created_at": "…", "verified_at": "…" }
  ]
}

스코프가 없으면 403 insufficient_scope입니다.

연결 해제 — 공개 엔드포인트가 없습니다

놀아 계정에는 현재 토큰을 폐기하는 공개 API(revoke 엔드포인트)가 없습니다. 서비스 쪽에서 «놀아 계정 연결 끊기»를 호출로 처리할 방법이 없다는 뜻입니다.

따라서 서비스는 401 invalid_token을 받았을 때 조용히 로그아웃 처리하도록 만들어 두세요. 사용자가 놀아 계정 쪽에서 연결을 정리했거나 토큰이 만료된 상황에서, 그것이 서비스가 알 수 있는 유일한 신호입니다.

서비스 자체 로그아웃은 서비스 세션만 지우면 됩니다. 놀아 계정 세션까지 끊을 필요는 없습니다.

에러 응답 형식

{ "error": "invalid_grant", "error_description": "pkce verification failed" }

error_description은 없을 수도 있습니다. 전체 목록은 에러 코드 사전에 있습니다.