Skip to content

finlab

FinLab core module providing login authentication and credential management.

Use Cases

  • Log in when using FinLab for the first time
  • Authenticate in different environments (local machine, Colab, servers, schedulers)
  • Check current login status

Quick Examples

Run this once in a terminal; every Python session on the same machine then reuses the stored credentials:

python -m finlab login

Or log in from Python / Jupyter:

import finlab

# Launch browser login (opens browser automatically)
finlab.login()

# After successful login, credentials are saved to ~/.finlab/credentials.json
# No need to log in again for subsequent use

Google Colab

import finlab

finlab.login()  # follow the prompt to finish logging in in the browser

Servers, Docker, schedulers (no browser)

First export credentials on a machine where you are logged in:

python -m finlab token --env
# export FINLAB_REFRESH_TOKEN="..."
# export FINLAB_SESSION_ID="..."
# export FINLAB_API_KEY="..."

Then set these three values as environment variables in the target environment (docker-compose, GitHub Actions secrets, Cloud Functions variables, ...). Your code does not need to call finlab.login():

from finlab import data

close = data.get('price:收盤價')  # picks up FINLAB_REFRESH_TOKEN etc. automatically

FINLAB_API_TOKEN is deprecated

The legacy FINLAB_API_TOKEN environment variable and finlab.login('YOUR_API_TOKEN') are deprecated and emit a DeprecationWarning. Use browser login or the three environment variables produced by python -m finlab token --env instead. Run python -m finlab migrate for a migration guide.

Authentication Method Comparison

Method Pros Cons Use Cases
Browser login (python -m finlab login / finlab.login()) Secure, convenient, auto-refreshes token Needs a browser Local development, Jupyter, Colab
Environment-variable credentials (python -m finlab token --env) No browser needed, nothing hardcoded Requires one local login first Servers, Docker, schedulers, CI
FINLAB_API_TOKEN (deprecated) — Deprecated, will be removed Please migrate

Authentication Priority

FinLab looks for credentials in the following order:

  1. FINLAB_REFRESH_TOKEN + FINLAB_SESSION_ID + FINLAB_API_KEY environment variables (only when all three are set)
  2. ~/.finlab/credentials.json - credentials generated by browser login
  3. FINLAB_ID_TOKEN environment variable - used by browser / Pyodide runtimes
  4. FINLAB_API_TOKEN environment variable - legacy API token (deprecated, warns)
  5. Interactive login - starts browser login if none of the above exist

Detailed Tutorial

Browser Login Flow

import finlab

# 1. Call login() without arguments
finlab.login()

# 2. Browser automatically opens the FinLab login page
# 3. After successful login, credentials are saved automatically
# 4. No need to log in again for subsequent use

Credential storage location: ~/.finlab/credentials.json

Validity period: 60 days (auto-refreshes)

If browser login fails, is rejected, or times out, finlab.login() raises finlab.exceptions.LoginError (a RuntimeError subclass) instead of returning silently.

Checking status and logging out

python -m finlab status   # show login status and plan
python -m finlab logout   # clear local credentials and remove the server session

API Reference

finlab.login()

finlab.login 

login(api_token=None)

登錄量化平台。

不傳入參數時啟動瀏覽器登入，成功後憑證存於 ~/.finlab/credentials.json， 之後同一台機器會自動使用。Colab 同樣直接呼叫 finlab.login()。 無瀏覽器的環境（伺服器、排程）請在本機執行 python -m finlab token --env， 並設定 FINLAB_REFRESH_TOKEN、FINLAB_SESSION_ID、FINLAB_API_KEY。

PARAMETER DESCRIPTION
api_token

已棄用的舊版 api_token，請改用瀏覽器登入。

TYPE: str DEFAULT: None

RAISES DESCRIPTION
LoginError

瀏覽器登入失敗、被拒絕或逾時。

Recommended Usage

  • Local development / Jupyter / Colab: python -m finlab login or finlab.login() browser login
  • Servers / schedulers / CI: run python -m finlab token --env locally and set FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID and FINLAB_API_KEY as environment variables

Credential safety

  • Never commit credential environment variables or ~/.finlab/credentials.json to GitHub or other public places
  • Use your platform's secrets feature or a .env file

finlab.get_token()

finlab.get_token 

get_token()

取得登錄會員的認證 token。

認證優先順序： 1. ~/.finlab/credentials.json (新版 Firebase auth) → 返回 id_token 2. FINLAB_ID_TOKEN 環境變數 (新版 Firebase auth) → 返回 id_token 3. FINLAB_API_TOKEN 環境變數 (舊版) → 返回 api_token 4. 互動式登入

RETURNS DESCRIPTION
tuple

(token_string, token_type) where token_type is 'id_token' or 'api_token'

TYPE: tuple[str, str]

FAQ

Q: How to check if logged in?

python -m finlab status

Or in Python:

import finlab

try:
    token, token_type = finlab.get_token()
    print(f"✅ Logged in ({token_type})")
except RuntimeError:
    print("❌ Not logged in")

Q: What if browser login fails?

finlab.login() raises LoginError with instructions. Common causes:

  1. Missing cryptography package 

    pip install cryptography

  2. No browser environment (e.g., server)

  3. Run python -m finlab login on your own machine, then python -m finlab token --env

  4. Set the printed FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID and FINLAB_API_KEY on the server

  5. Login timed out or blocked by a firewall

  6. Run finlab.login() again and finish the browser login before it expires
  7. Check network settings

Q: I still use FINLAB_API_TOKEN. What should I do?

Run python -m finlab migrate for the steps: use python -m finlab login locally, use the three variables from python -m finlab token --env in headless environments, then remove FINLAB_API_TOKEN.

Q: How to log out?

python -m finlab logout

If you set environment-variable credentials, also remove FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID, FINLAB_API_KEY (and the legacy FINLAB_API_TOKEN).

References