Connecting a helpdesk tool through the API

During the summer holidays, the Elmsbrück team answers many identical questions from families, such as “Does Alex have a place?”. A helpdesk tool is to look up the answers in fepli itself. For this it uses the API, the interface of fepli. You create a service account for it that may only read and that ends with the summer holidays. The tool answers only families whose identity is established. Your part of the work takes about 30 minutes; IT or the vendor sets up the tool itself.

What you need

• An account with the account type Admin and the role Super admin. Only super admins manage service accounts.
• A helpdesk tool or a support agent with artificial intelligence that can query an API with a token.
• The person who sets up the tool: the municipality's IT or the tool's vendor.
• A data processing agreement with the tool's vendor. If the tool uses a language model, you also need one with the language model's provider.
• A reviewed legal basis for every transfer to a third country, e.g. if the language model runs outside the European Union.
• A data protection impact assessment, agreed with the data protection office of your administration.
• A note to families that the tool answers their questions with data from fepli, e.g. in your privacy statement.
• A secure way to pass on passwords, e.g. the password manager of your administration.
• A participant account for testing, with an email address whose mailbox you read, e.g. helpdesk-test@example.org. It holds the participant Alex Beispiel with a registration for the canoe trip.
• An enabled interface. The app API is switched on by default: App-Store.

Step 1 – Create a service account

The tool needs an access of its own that is tied to no person. A service account keeps running when someone leaves the team, and logs show its name. A personal API token, by contrast, has all your roles and is deleted with your account.

1. Select Settings.
2. Switch to Integrations.
3. Select New service account.
4. Enter Helpdesk as Name.
5. Under Description, enter what the account is for and who is responsible for it, e.g. Helpdesk tool for questions from families. Responsible: Kim Beispiel.

The form shows name and description. Under Access and Roles, the defaults of fepli are still set.

Step 2 – Set access and roles

Read only is the upper limit for every token of the account: the tool changes nothing, even if a family asks it to. To answer the question about a place, the tool needs Admin to find accounts and registrations, and Participants to recognise the participants of an account; only Admin is preselected. Every further role gives the tool access to more data, so the other roles stay turned off.

1. Under Access, select Read only.
2. Under Roles, turn on Participants. Admin stays turned on, and the other roles stay turned off.
3. Select Save.

The page of the service account opens with the message “The service account has been created. Now create a token for it.” Beside the name Helpdesk, it shows Read only.

Step 3 – Create a token

The tool signs in with a token, a long string that works like a password. With a date under Valid until, the access ends by itself, even if nobody thinks of revoking it. The tool helps in the summer holidays, so the token ends on the last day of the holidays.

1. In the section New API token, enter Helpdesk tool under Label.
2. Under Valid until, enter 31.08.2027. Under Access, only Read only is available, because the service account may only read.
3. Select New API token.

The box Your new API token shows the token, which begins with svc-. Below it, under How to use it, there is a command for testing.

Step 4 – Pass on the token securely

fepli shows the token only this once. Whoever has it can read all accounts, registrations and participants with the permissions of the service account. Pass it on the same way as a password.

1. Copy the token from the box Your new API token.
2. Copy the command under How to use it. It contains the address of the API.
3. Hand over both to the person who sets up the tool, through the password manager.

As soon as you leave the page, fepli no longer shows the token. In the list Tokens, it appears shortened, with “Valid until {date}” and the note Never used.

Step 5 – Define and test who the tool answers

Through the service account, the tool reads the data of all families, but anyone can state a name. The tool therefore answers only when it is established who is asking: in a signed-in session or from a confirmed sender address that belongs to the account. Two test questions show that token, roles and this rule fit together.

1. Ask the person who sets up the tool to run the command from How to use it and then to follow the guide Support agents.
2. Agree with them that the tool gives information only about the account of the signed-in session or of the confirmed sender address. If someone gives only a name, the tool does not answer.
3. Ask the tool by email from helpdesk-test@example.org whether Alex Beispiel has a place in the canoe trip.
4. Compare the answer with the participant list of the Canoe trip.
5. Ask the same question from your own email address. It does not belong to the account of Alex Beispiel.
6. Select Settings and switch to Integrations.
7. In the row Helpdesk, select Open.

The row of the token now shows “Last used {date}”. The answer to the test account matches the participant list, and to the question from your own address, the tool gives no data on Alex Beispiel.

Step 6 – End the access when the tool is dropped

The token ends by itself on 31.08.2027. Revoke it earlier as soon as Elmsbrück switches the tool off or the token might have fallen into the wrong hands.

1. Open the page of the service account Helpdesk as in step 5.
2. In the row of the token Helpdesk tool, select Revoke.
3. Confirm the prompt “Integrations using the token lose access immediately.”

The message “The token has been revoked.” appears, and the token is no longer in the list. fepli rejects every further request with this token.

What you have achieved

The helpdesk tool of Elmsbrück looks up registrations and participants through a service account of its own and cannot change anything. It answers only families whose identity is established, and only about their own account. The access is tied to no person on the team and ends by itself with the summer holidays.

If your case is different

• If you write a script yourself, e.g. for an analysis, a personal API token under Security > API tokens is enough: Signing in and profile.
• If the tool is also to answer questions about receipts and open amounts, additionally turn on the role Payments: Roles and permissions.
• If Elmsbrück keeps using the tool after the summer holidays, create a new token with a later date under Valid until before 31.08.2027.
• If the tool is to rest for a while, select Disable on the page of the service account. fepli then rejects its tokens until you select Enable: Settings.
• If the tool is also to write notes for the team or, after your decision, withdraw registrations, it needs a service account with Read and write: Support agents.
• If Elmsbrück does not have a super admin yet, the operator of the installation creates the service account with a console command: Service accounts.

Where to go next

• Service accounts
• Settings
• Roles and permissions