API Clients

API Clients use OAuth 2.0 to authenticate users. This is the right choice when you're building a web application where users log in and interact with Moloni ON data.

Overview

The flow works like this:

You create an API Client in Moloni ON (this gives you a client ID and secret)
Your app redirects the user to Moloni ON to authorize access
Moloni ON redirects back with a code
Your server exchanges the code for an access token and refresh token
You use the access token to make API requests on behalf of that user

Creating an API Client

API Clients are managed from your Moloni ON account:

Log in to Moloni ON
Go to Account → API
Open the API Clients tab
Click Create
Enter a name for the client
Save. You'll be shown the client ID and client secret

Keep your secret safe

The client secret is shown only once. Store it securely; you'll need it during the OAuth flow.

If you lose it, you can regenerate it from the API Clients list, but the old secret will immediately stop working.

Migrating from company-based API Clients

API Clients were previously associated with a company and created via Tools → Developers → API Clients. This approach is deprecated.

API Clients are now associated with your user account and managed from the Account → API page. Existing company-based clients continue to work, but we recommend migrating to user-based clients.

OAuth 2.0 Flow

The complete flow from user authorization to an authenticated API request:

1. Authorize a User

Redirect the user to the Moloni ON authorization page:

https://api.molonion.pt/v1/auth/authorize?apiClientId=[yourAPIClientId]&redirectUri=[yourCallbackURL(URLEncoded)]

Parameter	Description
`apiClientId`	The client ID from the creation step
`redirectUri`	Your callback URL (must be URL-encoded)

Example:

https://api.molonion.pt/v1/auth/authorize?apiClientId=api:a1b2c3d4e5f6...&redirectUri=https%3A%2F%2Fwww.myapp.com%2Fcallback

The user will log in, grant authorization, and be redirected back to your redirectUri with a code in the query string.

The authorization code expires in 1 minute. Exchange it for tokens immediately.

2. Exchange Code for Tokens

Make a POST request to the grant endpoint:

POST https://api.molonion.pt/v1/auth/grant
Content-Type: application/x-www-form-urlencoded

Body parameters:

Parameter	Value
`grantType`	`authorization_code`
`code`	The code received in the redirect
`apiClientId`	Your API client ID
`clientSecret`	Your API client secret

Example with curl:

curl -X POST https://api.molonion.pt/v1/auth/grant \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grantType=authorization_code&code=RECEIVED_CODE&apiClientId=YOUR_CLIENT_ID&clientSecret=YOUR_SECRET"

Response:

{
  "accessToken": "[accessToken]",
  "accessTokenExpiracy": "[now plus one hour]",
  "refreshToken": "[refreshToken]",
  "refreshTokenExpiracy": "[now plus 14 days]"
}

3. Make Authenticated Requests

Use the access token in the Authorization header:

POST https://api.molonion.pt/v1
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

The access token is valid for 1 hour.

4. Refresh Tokens

When the access token expires, use the refresh token to get a new pair:

POST https://api.molonion.pt/v1/auth/grant
Content-Type: application/x-www-form-urlencoded

Parameter	Value
`grantType`	`refresh_token`
`refreshToken`	Your current valid refresh token
`apiClientId`	Your API client ID
`clientSecret`	Your API client secret

The response is the same format: a new access token and a new refresh token. The refresh token is valid for 14 days.

Once you receive a new refresh token, treat the previous one as expired: it is only guaranteed to keep working for about 60 seconds after its first use, to tolerate retries and requests from multiple tabs or processes. Always store the newest refresh token from the response and use that one going forward.

If you make at least one API call (even a read) every 14 days, you'll never have to re-authenticate.

Token lifecycle

Token	Expiry	Renewal
Access token	1 hour	Refresh with refresh token
Refresh token	14 days	Automatically renewed on use; keep the newest one, the previous is only guaranteed for about 60 seconds
Authorization code	1 minute	Not renewable; start the flow again

Your application should follow this logic on every request:

Managing API Clients

From the Account → API → API Clients tab you can:

View your API Client IDs and names
Regenerate a client secret (invalidates the old one immediately)
Delete API Clients you no longer need

Next steps

API Keys: For machine-to-machine usage without user interaction
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