인증 (auth)¶

키움증권 OAuth2 접근토큰 발급 및 유효성 관리를 담당하는 모듈입니다.

kiwoompy.auth ¶

인증 모듈 — OAuth2 접근토큰 발급 및 폐기 (au10001, au10002).

KiwoomAuth ¶

KiwoomAuth(api: KiwoomApi)

키움 REST API 인증 관리자.

접근토큰 발급 후 KiwoomApi 계층에 저장하여 이후 모든 API 호출에서 자동으로 재사용되도록 한다.

Parameters:

Name	Type	Description	Default
`api`	`KiwoomApi`	HTTP 클라이언트 인스턴스. 토큰을 발급 즉시 이 객체에 저장한다.	required

Source code in src/kiwoompy/auth.py

def __init__(self, api: KiwoomApi) -> None:
    self._api = api
    self._expires_at: datetime | None = None

is_token_valid ¶

is_token_valid() -> bool

현재 토큰이 유효한지 확인한다.

Returns:

Type	Description
`bool`	토큰이 발급되어 있고 아직 만료되지 않으면 `True`.

Source code in src/kiwoompy/auth.py

def is_token_valid(self) -> bool:
    """현재 토큰이 유효한지 확인한다.

    Returns:
        토큰이 발급되어 있고 아직 만료되지 않으면 ``True``.
    """
    if self._expires_at is None:
        return False
    return datetime.now() < self._expires_at

issue_token ¶

issue_token(appkey: str, secretkey: str) -> TokenResponse

접근토큰을 발급하고 API 클라이언트에 저장한다 (au10001).

Parameters:

Name	Type	Description	Default
`appkey`	`str`	키움증권 앱 키.	required
`secretkey`	`str`	키움증권 시크릿 키.	required

Returns:

Type	Description
`TokenResponse`	발급된 토큰 정보 (`TokenResponse`).

Raises:

Type	Description
`KiwoomAuthError`	앱 키·시크릿 키가 올바르지 않거나 인증 서버 4xx 응답.
`KiwoomApiError`	서버 5xx 오류, 네트워크 타임아웃, 응답 파싱 실패.

Source code in src/kiwoompy/auth.py

def issue_token(self, appkey: str, secretkey: str) -> TokenResponse:
    """접근토큰을 발급하고 API 클라이언트에 저장한다 (au10001).

    Args:
        appkey: 키움증권 앱 키.
        secretkey: 키움증권 시크릿 키.

    Returns:
        발급된 토큰 정보 (`TokenResponse`).

    Raises:
        KiwoomAuthError: 앱 키·시크릿 키가 올바르지 않거나 인증 서버 4xx 응답.
        KiwoomApiError: 서버 5xx 오류, 네트워크 타임아웃, 응답 파싱 실패.
    """
    request = TokenRequest(appkey=appkey, secretkey=secretkey)
    raw = self._api.post("/oauth2/token", asdict(request))

    response = self._parse_response(raw)
    self._api.set_token(response.token)
    self._expires_at = self._parse_expires_dt(response.expires_dt)
    return response

revoke_token ¶

revoke_token(appkey: str, secretkey: str) -> None

현재 발급된 접근토큰을 폐기하고 내부 상태를 초기화한다 (au10002).

폐기 후에는 해당 토큰으로 API를 호출할 수 없다. 성공 시 KiwoomApi에 저장된 토큰과 만료일시를 초기화한다.

Parameters:

Name	Type	Description	Default
`appkey`	`str`	키움증권 앱 키.	required
`secretkey`	`str`	키움증권 시크릿 키.	required

Raises:

Type	Description
`KiwoomAuthError`	토큰이 발급되지 않았거나 폐기 요청이 실패한 경우.
`KiwoomApiError`	서버 5xx 오류, 네트워크 타임아웃, 응답 파싱 실패.

Source code in src/kiwoompy/auth.py

def revoke_token(self, appkey: str, secretkey: str) -> None:
    """현재 발급된 접근토큰을 폐기하고 내부 상태를 초기화한다 (au10002).

    폐기 후에는 해당 토큰으로 API를 호출할 수 없다.
    성공 시 ``KiwoomApi``에 저장된 토큰과 만료일시를 초기화한다.

    Args:
        appkey: 키움증권 앱 키.
        secretkey: 키움증권 시크릿 키.

    Raises:
        KiwoomAuthError: 토큰이 발급되지 않았거나 폐기 요청이 실패한 경우.
        KiwoomApiError: 서버 5xx 오류, 네트워크 타임아웃, 응답 파싱 실패.
    """
    auth_header = self._api.get_auth_header()
    # get_auth_header()가 토큰 존재 여부를 검증하므로 이 시점에서 _token은 반드시 str
    token: str = self._api._token  # type: ignore[assignment]  # noqa: SLF001

    request = RevokeTokenRequest(appkey=appkey, secretkey=secretkey, token=token)
    raw = self._api.post(
        "/oauth2/revoke",
        {"appkey": request.appkey, "secretkey": request.secretkey, "token": request.token},
        headers={**auth_header, "api-id": "au10002"},
    )

    return_code = raw.get("return_code")
    if return_code is not None and return_code != 0:
        msg = raw.get("return_msg", "폐기 실패")
        raise KiwoomAuthError(f"접근토큰 폐기 실패 (return_code={return_code}): {msg}")

    self._api.set_token("")
    self._expires_at = None