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

data.set_market('us')
close = data.get('price:adj_close')  # 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()

def login(api_token: str | None = None) -> None

Log in to FinLab.

Called without arguments, it starts the browser login. On success the credentials are saved to ~/.finlab/credentials.json and reused automatically on the same machine. In Colab, call finlab.login() the same way. For environments without a browser (servers, schedulers), run python -m finlab token --env on your own machine and set FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID and FINLAB_API_KEY.

Parameter Type Description
api_token str or None Deprecated legacy API token. Use browser login instead.

Raises: LoginError when the browser login fails, is rejected, or times out.

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()

def get_token() -> tuple[str, str]

Return the authentication token of the logged-in member.

Credentials are looked up in this order:

  1. Login credentials: the FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID and FINLAB_API_KEY environment variables when all three are set, otherwise ~/.finlab/credentials.json from browser login; returns an id_token
  2. The FINLAB_ID_TOKEN environment variable, returns an id_token
  3. The legacy FINLAB_API_TOKEN environment variable, returns an api_token
  4. Interactive login

Returns: tuple of (token_string, token_type), where token_type is 'id_token' or 'api_token'.

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