Skip to content

finlab

FinLab core module providing login authentication and Token management.

Use Cases

  • Authenticate when using FinLab for the first time
  • Automatically set API Token in scripts
  • Authenticate across different environments (local, Colab, server)
  • Check current login status

Quick Examples

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

Method 2: API Token Login (Legacy, still supported)

import finlab

# Login with API Token
finlab.login('YOUR_API_TOKEN')

# Get your API Token: https://ai.finlab.tw/account

Method 3: Environment Variable Login

import os

# Set environment variable (suitable for script automation)
os.environ['FINLAB_API_TOKEN'] = 'YOUR_API_TOKEN'

# finlab will automatically read the environment variable
from finlab import data
close = data.get('price:收盤價')

Authentication Method Comparison

Method Pros Cons Use Case
Browser Login Secure, convenient, auto-refreshes Token Requires browser environment Local development, Jupyter Notebook
API Token Simple, suitable for automation Token expires, requires manual renewal Script automation, CI/CD
Environment Variable Secure, not hardcoded Requires additional setup Production environment, Docker

Authentication Priority

FinLab searches for authentication credentials in the following order:

  1. ~/.finlab/credentials.json - Credentials generated by browser login (new method)
  2. FINLAB_API_TOKEN environment variable - Manually set API Token (legacy method)
  3. Interactive login - If none of the above exist, prompts for login

Detailed Guide

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

Credentials location: ~/.finlab/credentials.json

Validity period: 60 days (auto-refreshed)

Getting an API Token

If using the API Token login method:

  1. Go to the FinLab Account Center
  2. Copy your API Token
  3. Use finlab.login('YOUR_API_TOKEN') in your code

Using in Different Environments

Google Colab

# Method 1: Browser login (recommended)
import finlab
finlab.login()

# Method 2: Use Colab Secrets (prevents Token leakage)
from google.colab import userdata
import finlab
finlab.login(userdata.get('FINLAB_API_TOKEN'))

Docker / Production Environment

# Use environment variables (set in docker-compose.yml or .env)
export FINLAB_API_TOKEN='YOUR_API_TOKEN'

# Python scripts will automatically read the environment variable
from finlab import data
close = data.get('price:收盤價')

Jupyter Notebook / Local Development

# First-time login
import finlab
finlab.login()  # Browser login

# No need to log in again for subsequent use (credentials are saved)
from finlab import data
close = data.get('price:收盤價')

API Reference

finlab.login()

finlab.login 

login(api_token=None)

登錄量化平台。

可以至 api_token查詢頁面 獲取api_token，傳入函數後執行登錄動作。 之後使用Finlab模組的會員功能時，系統就不會自動跳出請求輸入api_token的GUI頁面。 若傳入的api_toke格式有誤，系統會要求再次輸入。

若不傳入 api_token，會啟動瀏覽器登入流程（新版）。

PARAMETER DESCRIPTION
api_token

FinLab api_token

TYPE: str DEFAULT: None

Recommended Usage

  • Local development: Use finlab.login() for browser login (convenient and secure)
  • Automated scripts: Use the FINLAB_API_TOKEN environment variable (avoids hardcoding Token)
  • Test environment: Use finlab.login('token') for quick verification

API Token Precautions

  • Do not upload API Tokens to public platforms like GitHub
  • Use environment variables or .env files to manage Tokens
  • Tokens need to be re-obtained when expired

finlab.get_token()

finlab.get_token 

get_token()

取得登錄會員的認證 token。

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

RETURNS DESCRIPTION
tuple

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

FAQ

Q: How do I check if I am logged in?

import finlab

try:
    token, token_type = finlab.get_token()
    print(f"Logged in ({token_type})")
    print(f"Token: {token[:10]}...")
except Exception as e:
    print("Not logged in")

Q: What if browser login fails?

Possible causes and solutions:

  1. Missing cryptography package 

    pip install cryptography

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

  3. Switch to API Token method: finlab.login('YOUR_API_TOKEN')

  4. Firewall blocking

  5. Check network settings
  6. Switch to API Token method

Q: What if my API Token has expired?

# Re-obtain Token and log in
import finlab
finlab.login('NEW_API_TOKEN')

# Or use browser login (auto-refreshes)
finlab.login()

Q: How do I use different Tokens for multiple projects?

Use environment variables:

import os
import finlab

# Project A
os.environ['FINLAB_API_TOKEN'] = 'TOKEN_A'
# Use finlab...

# Project B
os.environ['FINLAB_API_TOKEN'] = 'TOKEN_B'
# Use finlab...

Q: How do I log out?

import os

# Clear environment variables
os.environ.pop('FINLAB_API_TOKEN', None)
os.environ.pop('finlab_id_token', None)

# Delete credentials file (generated by browser login)
import os
credentials_path = os.path.expanduser('~/.finlab/credentials.json')
if os.path.exists(credentials_path):
    os.remove(credentials_path)
    print("Logged out")

Resources