API Keys

API Keys provide direct authentication for machine-to-machine integrations. Unlike API Clients which require an OAuth flow with user interaction, API Keys can be used immediately, with no redirects, no authorization codes and no token exchanges.

When to use API Keys

API Keys are ideal for:

Server-side scripts: automated syncing, data imports/exports
Cron jobs: scheduled reports, periodic data pulls
Backend integrations: connecting Moloni ON with other systems
Development and testing: quick API access during development

If your use case involves a user logging in through a browser, use an API Client with OAuth 2.0 instead.

Creating an API Key

Log in to Moloni ON
Go to Account → API
Open the API Keys tab
Click Create
Enter a name (e.g. "Warehouse Sync", "Report Generator")
Optionally set an expiration date (defaults to 1 year; leave blank for no expiry)
Save. You'll be shown the API Key token

Store your token immediately

The API Key token is shown only once at creation. Copy and store it securely before closing the dialog.

The token format is: apik:{keyId}:{secret}

Using the API Key

Pass the token directly in the Authorization header, with no OAuth flow needed:

curl -X POST https://api.molonion.pt/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer apik:550e8400-e29b-41d4-a716-446655440000:3f8c9a2b1d4e7a5f" \
  -d '{
    "query": "query { customers(companyId: 1) { data { customerId name } } }"
  }'

That's it: no token exchange, no refresh flow. The API Key works directly as a Bearer token.

Permissions

An API Key inherits the permissions of the user who created it. If the user has read-only access to a company, the API Key will too.

Expiration

Setting	Behavior
With expiration date	Key stops working after that date
Without expiration date	Key works indefinitely until deleted

The default suggestion when creating a key is 1 year from today.

Expired keys cannot be renewed. Create a new key if the old one expires.

Regenerating a token

If a token is compromised, you can regenerate it from the Account → API → API Keys tab:

Find the key in the list
Click Regenerate
The old token is immediately invalidated
A new token is shown; store it before closing

The key ID and name stay the same; only the secret portion changes.

Revoking a key

To revoke an API Key, delete it from the Account → API → API Keys tab. This is immediate; any requests using that token will fail with a 401 Unauthorized error.

API Key vs API Client

	API Key	API Client (OAuth 2.0)
Setup	Create key → use token	Create client → OAuth flow → manage tokens
User interaction	None	Required (user authorizes via browser)
Token management	Single permanent token	Access token (1h) + refresh token (14d)
Expiration	Optional (configurable)	Access token expires hourly, refresh every 14 days
Best for	Scripts, cron jobs, integrations	Web apps acting on behalf of users

Next steps

API Clients: Set up OAuth 2.0 for web applications
Schema & Tooling: Set up your IDE and code generators with the API schema
Creating an Invoice: Create your first document
API Reference: Browse every query, mutation and type