Authentication

Real validation runs require a bearer token. Dry runs do not call the API and do not require a token.

Create A Token

The CLI uses the same Personal Access Tokens as the Integration API.

In the Optimus web app:

1. Open Settings.
2. Select the API Interface tab.
3. In API Tokens, click Create Token.
4. Enter a descriptive Token Name, such as Nightly customer VAT check.
5. Optionally add Allowed IP ranges for the machine or network that will run the CLI.
6. Click Create Token.
7. Copy the token immediately.

The token secret is only shown once. After creation, Optimus shows the token prefix and masked characters, but not the full secret.

Allowed IP ranges accept exact IPv4 addresses and IPv4 CIDR ranges. Leave the field empty only when the token may be used from any IP address.

Configure The Token

Set the token with OPTIMUS_TOKEN:

export OPTIMUS_TOKEN="<token>"

Or pass it directly:

optimus check customers.csv --map mapping.yml --standard --token "<token>"

The environment variable is preferred because it avoids putting the token directly in command history.

Do not include real tok_optimus_ token values in scripts committed to source control, screenshots, support tickets, or documentation examples.

API Target

The CLI resolves the API target in this order:

1. --base-url
2. OPTIMUS_BASE_URL
3. --env or OPTIMUS_ENV
4. Production URL

Use the production API:

optimus check customers.csv --map mapping.yml --standard --env prod

Production uses:

https://app.optimussoftware.de/

Use the test API:

optimus check customers.csv --map mapping.yml --standard --env test

Test uses:

https://dev.app.optimussoftware.de/

Override the full base URL:

optimus check customers.csv --map mapping.yml --standard --base-url "https://example.test/"

--base-url must be an absolute URL.

Authentication Errors

Message	Meaning	Fix
No token configured. Set --token or the OPTIMUS_TOKEN environment variable.	The command would call the API but no token was available.	Set OPTIMUS_TOKEN or pass --token.
Token is invalid or expired.	The API rejected the token.	Create a new token in Settings > API Interface > API Tokens and update the CLI environment.
Token is invalid or expired.	The token is restricted to allowed IP ranges and the CLI is running from another IP address.	Edit the token IP ranges or create a token for the machine running the CLI.
Quota exhausted. Please check your license.	The account does not have remaining entitlement for the request.	Check license and quota.

Support logs do not write tokens.