REST API

Service accounts

A service account is an identity for a machine rather than a person: an integration, a reporting job, an AI support agent. It has its own roles, it keeps working when colleagues leave, and it can be capped at read-only no matter which tokens are created for it.

Why not a personal token?

A personal access token acts as the colleague who created it. That's fine for trying things out, but not for something that keeps running:

When the colleague leaves or loses a role, the integration stops working, or it quietly gains access when they are promoted.
Everything the integration does is logged as the colleague's own work.
You can't give the integration less than the colleague has.

A service account fixes all three. It has exactly the roles you give it, its actions are recorded under its own name, and its access level decides once and for all whether any of its tokens may write.

A service account signs in with API tokens only. It has no password and can't open the admin.

Create a service account

Service accounts are managed by super admins:

In the admin, open Einstellungen → Integrationen → API and choose Service-Accounts verwalten.
Choose Neuer Service-Account and fill in:
- Name: how the team recognises it, for example "Support-Agent". The name appears in logs and on comments the account writes.
- Beschreibung: what the account is for and who is responsible for it.
- Zugriff: Nur lesen or Lesen und schreiben. See Access level.
- Rollen: which sections of the admin the account can see. See Roles.
On the account's page, create a token under Tokens. Give it a label, choose its Zugriff, and if you like an expiry date. Lesen und schreiben is only offered when the account's own access level allows writing, and a disabled account can't get new tokens.
Copy the token. It starts with svc- and is shown this one time only.

Roles

A service account gets the same roles as a colleague. They decide which endpoints it can use (see Permissions):

Role	Admin label	Unlocks
`ROLE_ADMIN`	Admin	offers, editions, organisers, applications, accounts, consents, comments, outbox, search
`ROLE_PARTICIPANTS_ADMIN`	Teilnehmer:innen	participants (single participants also need Admin)
`ROLE_PAYMENTS_ADMIN`	Zahlungen	receipts, debtors
`ROLE_SUPER_ADMIN`	Super-Admin	everything: includes Admin, Teilnehmer:innen and Zahlungen, plus creating admin accounts and changing admin roles
`ROLE_HOST`	Veranstaltende	editions and categories only, see below

A new service account gets Admin, Teilnehmer:innen and Zahlungen by default: everything a support agent needs to look up a family's case.

Organiser users see the offers of the organisers they are members of. A service account is not a member of any organiser, so with Veranstaltende alone it sees no offers and no organisers. The same goes for any service account without Admin: even the published offers only come back without a token. Give it Admin if it needs offers.

A service account always belongs to exactly one municipality. The global admin role of multi-tenant installations can't be given to it.

Access level

The access level is the ceiling for every token the account holds:

read (Nur lesen): every token of the account can only read, even one that was created with write access before the account was restricted. A read-only service account can be given every endpoint to look at without ever being able to change anything.
write (Lesen und schreiben): tokens can read and, if they were created with write access, also write.

Changing the access level takes effect on the next request of every token.

Create one from the command line

On the server, ferienpass:api:service-account creates a service account and its first token in one go. That's useful for provisioning an integration without a browser, or for a new municipality where no super admin has signed in yet.

A read-only support agent

bin/console ferienpass:api:service-account "Support-Agent" --tenant=musterstadt

A writing integration with an expiring token

bin/console ferienpass:api:service-account "Zapier" --tenant=musterstadt \
  --access=write --role=ROLE_ADMIN --valid-until="+1 year"

Name
name
Type
argument
Description
A name the team recognises the account by. Required.
Name
--tenant
Type
string
Description
The municipality (its slug). Required on multi-tenant installations; run ferienpass:tenant:list to see them.
Name
--access
Type
string
Description
read (default) or write.
Name
--role
Type
string
Description
A role to grant, repeatable. Accepts ROLE_ADMIN or just admin. Defaults to ROLE_ADMIN, ROLE_PARTICIPANTS_ADMIN and ROLE_PAYMENTS_ADMIN.
Name
--description
Type
string
Description
What the account is for.
Name
--token-name
Type
string
Description
A label for the first token.
Name
--valid-until
Type
string
Description
Expiry of the first token, as a date (2027-01-01) or relative (+90 days).
Name
--no-token
Type
flag
Description
Create the account only, and create tokens in the admin later.

The command prints the token once. Store it like a password.

Manage tokens

A service account can hold several tokens, for example one per environment. On the account's page you see when each token was last used (to within five minutes), and you can:

Revoke a token. It stops working immediately. Do this when a token is no longer needed or may have leaked.
Disable the account. All its tokens are refused with 401 (Service account disabled) until you enable it again. Use this to pause an integration without losing its setup.
Delete the account. Deletes it together with all its tokens.

What a service account leaves behind

Actions taken through a service account are recorded under its name where fepli keeps an author:

Comments it writes show its name as authorName.
Receipts it records have no recordedBy, because that field points to a person's account.
Offers it creates get no contact person or participant list recipient automatically. Send contact and participantListRecipientEmails yourself.
Offer workflow transitions it applies (publish, cancel, …) are not written to the offer's history in the admin.