CLI authentication
Commands that call the Tomba API need credentials. Sign in once with tomba login, or pass a key and secret with each command.
Log in
Code
tomba login signs you in through your browser with the OAuth 2.0 device flow. The CLI prints a URL and a one-time code and tries to open the URL; approve the request in Tomba, and the CLI saves the session and refreshes it when needed. You can open the URL on any device, so this also works over SSH. The CLI requests the read, search, verify, enrich, leads, and account scopes (OAuth 2.0).
After a browser login, each command first exchanges the session for your API secret (GET /v1/me) and the first key that GET /v1/keys returns, then calls the API with them. Your account therefore needs at least one API key, and these two requests count toward your rate limits on every run. For scripts and frequent runs, sign in with a key instead.
To sign in with an API key and secret:
Code
The CLI prompts for the key and the secret, checks them with GET /v1/me, and saves them. Get both from Get your key and secret. tomba login doesn't accept --key and --secret; passing them prints Please logout to login.
Credentials are saved in ~/.tomba.json. Run tomba whoami to confirm which account the CLI uses.
~/.tomba.json stores your secret, or your OAuth tokens, in plain text, and
by default other users of the machine can read it. Restrict it with chmod 600 ~/.tomba.json.
Pass credentials per command
For CI jobs and one-off runs, pass the key and secret as flags:
Code
The CLI doesn't read credentials from environment variables; -k/--key and -s/--secret are the only way to pass them. It picks credentials in this order:
- A browser session saved by
tomba login. - A key and secret saved by
tomba login --api-key. - The
--keyand--secretflags.
The flags are ignored while credentials are saved. To use different credentials, run tomba logout first.
Log out
Code
tomba logout clears the saved key, secret, and OAuth tokens from ~/.tomba.json. It doesn't revoke anything on the server: revoke the CLI's browser session under Connected apps, and replace a key you no longer trust as described in Rotate keys.
Troubleshooting
| Message | Cause and fix |
|---|---|
please sign in to your account, not logged in | No saved credentials and no --key and --secret flags. Run tomba login, or pass the flags. |
Please logout to login. | Credentials are already saved, or you passed --key and --secret to tomba login. Run tomba logout, then log in again. |
OAuth token expired. Please run 'tomba login' to re-authenticate. | The CLI couldn't refresh the saved session. Run tomba logout, then tomba login. |
Could not retrieve API credentials: no API keys found | Your account has no API key. Create one on the API keys page, or log in with tomba login --api-key. |
error: 400 Bad Request or error: 401 Unauthorized after a browser login | The first key that GET /v1/keys returns is the oldest key in your workspace. If it has expired or belongs to a teammate, the API rejects it with your secret. Log in with tomba login --api-key and your own key. |
error: 400 Bad Request with saved or passed credentials | The key may have expired (Key expiry). |
error: 401 Unauthorized with saved or passed credentials | The key doesn't exist or doesn't match the secret, or the account can't use the API. See Status codes. |