API Authentication

Integration API requests use bearer authentication with an Optimus Personal Access Token.

The same token model is used by Integration CLI and the Integration API. Create a separate token for each production integration so it can be revoked or IP-restricted without affecting other systems.

Create A Token In Optimus

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.
5. Optionally add Allowed IP ranges.
6. Click Create Token.
7. Copy the token immediately.

The token secret is only shown once after creation. After the dialog is dismissed, the web app only shows the token prefix and masked characters.

The API Tokens page also links to the Integration API documentation, where you can authenticate and try requests.

Allowed IP Ranges

Allowed IP ranges restrict where the token can be used from.

• Leave the field empty to allow requests from any IP address.
• Add exact IPv4 addresses or IPv4 CIDR ranges to restrict access.
• Press Enter after each IP address or CIDR range in the create-token dialog.
• You can edit allowed IP ranges later from the token list.

Examples:

203.0.113.10
203.0.113.0/24

Send The Token

Send the token in the Authorization header:

Authorization: Bearer <token>

Example request:

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/resolve?vatId=DE284700631" \
  -H "Authorization: Bearer <token>"

Do not include the tok_optimus_ token value in source code, issue trackers, logs, screenshots, or documentation examples.

Base URLs

Environment	Base URL
Production	https://app.optimussoftware.de
Test	https://dev.app.optimussoftware.de

Use the test base URL while validating a test integration. Use production only when the client is ready to validate real VAT data.

Try Requests In The API Reference

Open the Integration API documentation from the API Tokens page, authenticate with your token as a bearer token, and then use the generated endpoint reference to inspect requests.

If you are using curl, include the same header manually:

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/resolve?vatId=DE284700631" \
  -H "Authorization: Bearer <token>"

Manage Existing Tokens

The API Tokens list shows:

• Token name.
• Token prefix with the rest masked.
• Created date.
• Last used date when available.
• Expiration status.
• Allowed IP ranges.

Use Edit IP ranges to update allowed source IPs. Use Revoke to permanently disable a token. Revoking a token cannot be undone, and applications using that token will no longer be able to access the API.

Authentication Failures

Status	Meaning	Fix
401	Token is missing, invalid, expired, or revoked.	Create a new token in Settings > API Interface > API Tokens and update your client.
403	Token is recognized but not allowed to access the resource, or the request is not allowed from the current IP address.	Check token permissions, account access, and allowed IP ranges.