Skip to main content
This page explains how the Fintoc CLI resolves and stores your API key. It also explains how to switch keys between commands and between the test and live modes. When you run fintoc login, the CLI stores your secret key in ~/.fintoc/config.toml with file mode 0600, readable only by the current OS user. You can also pass keys inline or through an environment variable for scripting and CI.

​
Key resolution order

The CLI resolves the API key in this order of precedence:
  1. The --api-key flag passed inline on the command.
  2. The FINTOC_API_KEY environment variable.
  3. The key stored in ~/.fintoc/config.toml by fintoc login.
Whichever source resolves first wins. This precedence lets you keep a default test-mode key in your config file and override it per command. Use the override to switch between Fintoc organizations or between test and live mode.

​
View your active configuration

This command prints the API key currently in use (masked), the resolved environment, and the path of the config file.

​
Switch keys

To change the persisted key, log out and log back in:
To override the persisted key for a single command:

​
Use the CLI in CI

For CI/CD pipelines, set FINTOC_API_KEY as a secret environment variable in your provider (for example, GitHub Actions or CircleCI) and avoid persisting credentials to disk:
This approach avoids the interactive fintoc login flow and keeps the key out of shell history.

​
Test mode vs live mode

Each Fintoc API key is scoped to either test mode or live mode. The CLI infers the mode from the key’s prefix:
  • sk_test_... for test mode. Test mode never moves real money: the CLI creates no real payments or refunds.
  • sk_live_... for live mode. Commands run with this key create real payments and refunds on your production organization.
The CLI runs against both test and live mode. Resource commands (such as fintoc payment_intents list) work with either key. Commands that simulate events, such as fintoc trigger, run only in test mode and return an error with a live-mode key. Interactive fintoc login defaults to test mode. To authenticate in live mode, pass --mode live: