Authentication

The Ferienpass API supports two modes of access: unauthenticated (public) and authenticated (using a Personal Access Token).

Unauthenticated access

Most data — specifically offers that are published and part of an active holiday programme — is publicly accessible without any authentication. This is the same data shown on the Ferienpass website.

Unauthenticated request

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

For authenticated access (e.g. host organizations accessing their own offers), the API uses Personal Access Tokens (PAT). Tokens are created in the Ferienpass admin panel under your account settings.

A token has the following format:

pat-{secret-token}

Tokens can be scoped to specific permissions and have an optional expiry date.

Sending the token

Pass the token in the Authorization header using the Bearer scheme:

Authenticated request

curl https://ferienpass-musterstadt.de/api/offers \
  -H "Authorization: Bearer pat-abc123.secretvalue"

Keep your token secret — treat it like a password. If a token is compromised, revoke it immediately from the admin panel and create a new one.

Rate limiting

The Ferienpass API enforces rate limits to ensure stability and fair usage. The limits are based on your authentication status:

Unauthenticated requests: 5 requests per minute per IP address.
Authenticated requests: 50 requests per minute per user account.

If you exceed these limits, the API returns a 429 Too Many Requests response.

Error responses

If authentication fails, the API returns a 401 Unauthorized response:

Invalid token response

{
  "type": "https://tools.ietf.org/html/rfc2616#section-10",
  "title": "An error occurred",
  "detail": "Invalid credentials.",
  "status": 401
}