Authentication

Possfer uses JWT bearer tokens for API authentication. Obtain a token via login or registration, then include it in the Authorization header of every subsequent request.

Rate Limiting

All public authentication endpoints are rate-limited to 10 requests per minute per IP address. Exceeding this limit returns a 429 Too Many Requests response.

POST/api/auth/loginPublic

Authenticate with email and password to receive a JWT access token. Rate limited to 10 requests per minute.

Request Body

Name	Type	Required	Description
`email`	`string`	Required	The user's email address.
`password`	`string`	Required	The user's password (min 8 characters).

json

{
  __PH0__: "owner@mein-restaurant.de",
  __PH2__: "sicheresPasswort123"
}

Response 200 OK

json

{
  __PH0__: "eyJhbGciOiJIUzI1NiIs...",
  __PH2__: {
    __PH3__: "550e8400-e29b-41d4-a716-446655440000",
    __PH5__: "owner@mein-restaurant.de",
    __PH7__: "Max",
    __PH9__: "Mustermann",
    __PH11__: "owner",
    __PH13__: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
}

Error Responses

json

// 400 Bad Request - Missing fields
{
  __PH1__: "email and password are required"
}

json

// 401 Unauthorized - Invalid credentials
{
  __PH1__: "invalid credentials"
}

Examples

bash

curl -X POST https://api.possfer.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@mein-restaurant.de",
    "password": "sicheresPasswort123"
  }'

Register

POST/api/auth/registerPublic

Create a new account along with a restaurant. Returns a JWT token for immediate use. Rate limited to 10 requests per minute.

Request Body

Name	Type	Required	Description
`email`	`string`	Required	Account email address.
`password`	`string`	Required	Account password (min 8 characters).
`first_name`	`string`	Required	Owner's first name.
`last_name`	`string`	Required	Owner's last name.
`restaurant`	`object`	Required	Restaurant details (see nested fields below).

Restaurant Object

Name	Type	Required	Description
`name`	`string`	Required	Public display name of the restaurant.
`legal_name`	`string`	Required	Legal business name (as registered with the Finanzamt).
`tax_id`	`string`	Required	German tax ID (Steuernummer or USt-IdNr.).
`street`	`string`	Required	Street name.
`house_number`	`string`	Required	House number.
`postal_code`	`string`	Required	German postal code (PLZ, 5 digits).
`city`	`string`	Required	City name.

Defaults

The following fields are automatically set for new restaurants: country=DE, currency=EUR, timezone=Europe/Berlin.

json

{
  __PH0__: "info@gasthaus-zur-linde.de",
  __PH2__: "meinSicheresPasswort!",
  __PH4__: "Anna",
  __PH6__: "Schmidt",
  __PH8__: {
    __PH9__: "Gasthaus zur Linde",
    __PH11__: "Gasthaus zur Linde GmbH",
    __PH13__: "DE123456789",
    __PH15__: "Hauptstraße",
    __PH17__: "42",
    __PH19__: "10115",
    __PH21__: "Berlin"
  }
}

Response 201 Created

json

{
  __PH0__: "eyJhbGciOiJIUzI1NiIs...",
  __PH2__: {
    __PH3__: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    __PH5__: "info@gasthaus-zur-linde.de",
    __PH7__: "Anna",
    __PH9__: "Schmidt",
    __PH11__: "owner",
    __PH13__: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

Error Responses

json

// 400 Bad Request - Validation error
{
  __PH1__: "email is already in use"
}

json

// 500 Internal Server Error
{
  __PH1__: "failed to create account"
}

Get Current User

GET/api/auth/meProtected

Returns the JWT claims for the currently authenticated user. Useful for verifying tokens and retrieving session context.

Request Headers

Name	Type	Required	Description
`Authorization`	`string`	Required	Bearer token, e.g. "Bearer eyJhbGci..."

Response 200 OK

json

{
  __PH0__: "550e8400-e29b-41d4-a716-446655440000",
  __PH2__: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  __PH4__: "owner"
}

bash

curl https://api.possfer.com/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

POST/api/auth/pin-loginProtected

Quick staff switching on a shared POS terminal. Requires an existing valid JWT (from the restaurant's owner or manager session) and a staff member's 4-digit PIN. Rate limited to 10 requests per minute.

Use Case

PIN login is designed for shared POS terminals where multiple staff members work in shifts. The terminal stays logged in under the restaurant's master session, and individual staff members authenticate via their PIN for order attribution and accountability.

Request Body

Name	Type	Required	Description
`pin`	`string`	Required	4-digit staff PIN code (configured in staff management).

json

{
  __PH0__: "1234"
}

Response 200 OK

json

{
  __PH0__: "eyJhbGciOiJIUzI1NiIs...",
  __PH2__: {
    __PH3__: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    __PH5__: "kellner1@mein-restaurant.de",
    __PH7__: "Thomas",
    __PH9__: "Becker",
    __PH11__: "waiter",
    __PH13__: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
}

Error Responses

json

// 401 Unauthorized - Invalid PIN
{
  __PH1__: "invalid pin"
}

Using Tokens

Include the JWT token in the Authorization header as a Bearer token for all protected endpoints:

bash

curl https://api.possfer.com/api/orders \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Expiry

JWT tokens expire after 24 hours. When a token expires, the API returns 401 Unauthorized. Re-authenticate via the login endpoint to obtain a new token.

Authentication

Login

Request Body

Response 200 OK

Error Responses

Examples

Register

Request Body

Restaurant Object

Response 201 Created

Error Responses

Get Current User

Request Headers

Response 200 OK

PIN Login

Request Body

Response 200 OK

Error Responses

Using Tokens