API authentication

Every request to the API runs on behalf of an invoiceR user. The application has exactly the permissions this user has through their roles.

Tip

Create a separate technical user for each connected application and give it only the roles the application really needs. That way you see in the document history which changes come from the interface, and you can block the access specifically if needed.

invoiceR supports two ways of logging in to the API:

Method	Header	Validity	Suitable for
Access token	Authorization: Bearer <token>	short, issued anew at every login	Applications that may know user name and password
Personal access token (PAT)	Authorization: PAT <token>	until the chosen expiry date, one year by default	Services and scripts that should run without a password

Access token with user name and password

1. Send the user name (or e-mail address) and password to POST /api/TokenAuth/Authenticate:

   POST https://<server>/api/TokenAuth/Authenticate
   Content-Type: application/json
   
   { "userNameOrEmailAddress": "api-user", "password": "<password>" }

2. The response contains the access token in the field result.accessToken.

3. Send the token in the header of every further request:

   Authorization: Bearer <accessToken>

When the token expires, log in again.

Note

This login only works for users with a password in invoiceR. For interfaces, a technical user with its own password is therefore a good choice.

Personal access token (PAT)

A personal access token belongs to exactly one user. An application that uses it acts with the permissions of this user without knowing their password.

Creating a PAT

You create a PAT through the API, logged in as the user who should own the token:

1. Log in as this user (for example as above with user name and password, or in the Swagger UI).

2. Call POST /api/services/app/Authentication/CreatePersonalAccessToken and specify until when the token should be valid:

   POST https://<server>/api/services/app/Authentication/CreatePersonalAccessToken
   Authorization: Bearer <accessToken>
   Content-Type: application/json
   
   { "validUntil": "2027-10-31T00:00:00Z" }

   If you omit validUntil, the token is valid for one year. invoiceR rejects a date in the past.

3. The response contains the token in plain text. Store it immediately in a safe place, for example in a password vault or in the configuration of the application.

The token is shown only once

invoiceR only stores a hash of the token. It cannot show you the token again later. If it is lost, create a new one.

Using a PAT

Send the token with every request in the Authorization header with the prefix PAT:

GET https://<server>/api/services/app/Session/GetCurrentLoginInformations
Authorization: PAT <token>

invoiceR rejects the token if it has expired or if the user or the tenant is deactivated or deleted. Replace an expired token with a new one.

Danger

A PAT is as powerful as its user’s account. Do not pass it on, do not store it in source code or tickets, and choose an expiry date that fits the application. If a token becomes known, deactivate the user immediately and contact support.

A new token does not invalidate the old one: once the user is active again, the old token stays valid until its expiry date. Only reactivate the user after support has invalidated the exposed token or it has expired.

Note

There is no overview of issued tokens and no way to revoke individual tokens in the user interface yet. This section will be extended.