HHarperHarbor
콘솔

Open API v1

퀵스타트

Open API v1의 OAuth 절차를 설명합니다. 먼저 앱 연동을 신청한 뒤 제공된 설정에 따라 등록, 승인, API 호출을 진행하세요.

연동 신청

  1. 1 · 클라이언트 등록

    오리진당 한 번 등록합니다. 리디렉션 URI는 https여야 하며(개발 시 localhost 허용) 프래그먼트를 포함할 수 없습니다. 반환된 client_id를 저장하세요.

    POST https://api.harperharbor.com/oauth/register
Content-Type: application/json

{
  "client_name": "Your app",
  "redirect_uris": ["https://app.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"]
}

→ 201 { "client_id": "…" }

  2. 2 · 사용자 승인 요청

    PKCE(S256) 인가 코드. resource 지시자를 포함하면 토큰이 오픈 API 대상에 묶입니다.

    https://api.harperharbor.com/oauth/authorize
  ?response_type=code
  &client_id=…
  &redirect_uri=https://app.example.com/oauth/callback
  &resource=https://api.harperharbor.com/open/v1
  &state=…
  &code_challenge=…            # base64url(sha256(verifier))
  &code_challenge_method=S256

  3. 3 · 코드 교환

    코드와 verifier를 토큰 엔드포인트에 POST합니다. 액세스 토큰과 리프레시 토큰을 받습니다.

    POST https://api.harperharbor.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=…&client_id=…
&redirect_uri=…&code_verifier=…&resource=https://api.harperharbor.com/open/v1

→ 200 { "access_token": "…", "refresh_token": "…", "expires_in": 3600 }

  4. 4 · 첫 호출

    Authorization 헤더에 Bearer 토큰을 설정하고 language 헤더를 포함합니다. 응답의 사용자 ID는 공개 숫자 ID이며 내부 계정 식별자는 포함되지 않습니다.

    GET https://api.harperharbor.com/open/v1/me
Authorization: Bearer <access token>
language: en

→ 200 { "id": 100001, "nickname": "Aoi" }

요청 헤더

AuthorizationBearer <access token>
languagezh-Hant · zh-Hans · en · ja · ko
fromweb (선택 사항)

오류

JSON 오류에는 코드, 메시지, 재시도 가능 여부가 포함됩니다. 401 응답이면 토큰 갱신을 시도하세요. 인증이 계속 실패하면 사용자에게 다시 승인을 요청하세요.

{ "error": "unauthorized | forbidden | not_found | internal",
  "message": "…",
  "retryable": true }

한도

앱마다 사용량을 제한하는 일일 포인트 한도가 있습니다. 한도에 따른 추가 요금은 없습니다. 개발자 콘솔에서 앱, 서비스, 레인별 사용량을 확인할 수 있습니다.

API 명세 읽기 →