Quickstart

This guide takes you from nothing to an authenticated call in five minutes. You'll find your endpoint, list the public offers, get a token, check what it can do and then use it.

1. Find your endpoint

Every municipality runs its own fepli, so every municipality has its own API endpoint:

• By default, the API sits on the admin's host under /api. If you open the admin at https://ferienpass-musterstadt.de/admin, the API is at https://ferienpass-musterstadt.de/api.
• If the municipality gave the API a domain of its own, the API sits at the root of that domain, for example https://api.ferienpass-musterstadt.de. On that domain the /api prefix is dropped.

Super admins see the endpoint under Einstellungen → Integrationen → API, in the Endpunkt row. On an installation for a single municipality it shows just /api, which means the admin's own host.

All examples in this documentation use https://ferienpass-musterstadt.de/api as the base URL. Paths such as /offers are relative to it.

2. Make a public request

The published offers of the editions that are online can be read without a token, as long as public access is switched on. Try it:

curl https://ferienpass-musterstadt.de/api/offers

You get back a JSON array of offers. If you only want to show offers on a website, you can stop here and read Offers on your website.

3. Get a token

Everything else needs a token. There are two kinds:

• A personal access token acts as you, with your roles. Create one in the admin: open your user menu, choose Passwort ändern, and on the Sicherheit page go to API-Tokens → Neuer API-Token. This is the quickest way to try things out.
• A service account token acts as a service account, a machine identity with its own roles. Use one for anything that keeps running: an integration, a reporting job, an AI agent. Super admins create them under Einstellungen → Integrationen → API → Service-Accounts.

When you create a token, choose Nur lesen (read-only) unless you need to change data. The token is shown once. Copy it and keep it somewhere safe, then put it into an environment variable for the examples below:

export FEPLI_TOKEN='svc-…'

4. Check who you are

Send the token as a bearer token in the Authorization header. The first call to make is GET /me: it tells you who the token belongs to, which roles it has and whether it can write.

curl https://ferienpass-musterstadt.de/api/me \
  -H "Authorization: Bearer $FEPLI_TOKEN"

{
  "identifier": "service-account:0193b2d6-5c1e-7a48-9e0f-4d2a6b8c1e10",
  "type": "service-account",
  "uuid": "0193b2d6-5c1e-7a48-9e0f-4d2a6b8c1e10",
  "name": "Support-Agent",
  "roles": [
    "ROLE_ADMIN",
    "ROLE_PARTICIPANTS_ADMIN",
    "ROLE_PAYMENTS_ADMIN",
    "ROLE_USER",
    "ROLE_SERVICE_ACCOUNT"
  ],
  "scopes": ["api:read"],
  "access": "read",
  "tenant": { "slug": "musterstadt", "name": "Ferienpass Musterstadt" }
}

A 401 here means the token is wrong, expired, or belongs to a disabled service account. See Authentication.

5. Use the token

With a token, the offers endpoint returns every offer you may see in the admin, drafts included, along with the internal fields. The other endpoints open up according to your roles. For example, you can find everything that matches a family's name:

curl "https://ferienpass-musterstadt.de/api/search?q=Müller" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

{
  "query": "Müller",
  "offers": [],
  "editions": [],
  "participants": [
    { "uuid": "0191c7b3-1f2a-7c4d-8e5f-6a7b8c9d0e06", "name": "Lena Müller" }
  ],
  "accounts": [
    { "uuid": "0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05", "name": "Anna Müller" }
  ],
  "hosts": [],
  "receipts": [
    { "uuid": "0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08", "name": "RE-142" }
  ]
}

Every reference in a response carries a uuid. Use it to fetch the full record, for example GET /accounts/{uuid}.

What's next?

• Authentication: token types, scopes and what happens when a token is refused
• Permissions: which roles unlock which endpoints
• Conventions: identifiers, dates, amounts, filters and how PATCH works
• Offers: the reference for the most-used resource