MesseApp API Documentation

This document supplements the Swagger API documentation for the MesseApp backend.
It explains usage rules that are not obvious from the Swagger UI alone.

If you are a Developer that wants to update the code, please refer to the Developer Documentation,
as well as the ArchitectureInfo.

Other resources: API Requirements for Event Synchronization

Table of Contents

API Versioning and Base URL

  • All endpoints are versioned. The version appears in the URL as api/v{version}/....
  • When Swagger shows multiple versions, always call the intended version explicitly in your requests.

Authentication and Authorization

Overview

The MesseApp backend uses a unified JWT-based authentication model.
Access can be granted either through a chefsculinar user login (via POST /api/v1.0/Auth/User) or an API key ( via POST /api/v1.0/Auth/ApiKey).
All tokens follow official JWT standards and contain claims that define both the user's identity and their rights.

Policies vs. Roles

  • Policies define higher-level access requirements (e.g., Moderation, Administrative) that control who may access certain endpoints.
    Policies are evaluated in addition to normal authentication and are automatically assigned by the system based on the user’s role.
  • Roles (such as exhibitor, messeteam, administrator, etc.) describe a user’s position and permissions within the system’s business logic.
    They influence both business and access logic (e.g., available actions, editable data, or storage paths) and are tightly integrated with policy application.

Example:
A user with the messeteam role — and therefore the Moderation policy — cannot directly modify data that is currently restricted to an exhibitor for editing.

Entity-Scoped User Rights

  • Rights are evaluated per entity, such as a specific Booth or DigitalBooth.
  • Each right level grants incremental access depending on the context, but in general:
Level Description
Assigned Can see that an entity exists (e.g., lists or metadata) but cannot download or modify any content unless explicitly allowed.
Read Can view detailed information and download related media or data.
Write Can create or modify resources (e.g., orders, media entries, or booth configuration), provided no business rule blocks the action.

Practical Examples

  • A user assigned to a Booth can see that data exists (e.g., uploaded media or order information),
    but cannot download or modify it without explicit Read or Write rights.
  • In a DigitalBooth, an assigned user can see that stories are available or that navigation elements exist,
    even without Read rights.
  • Data required for navigation within the system is always accessible with the Assigned right level.

How Rights Are Evaluated

When performing authorization checks, the system evaluates access in the following order:

  1. Authentication:
    The user’s identity is validated via a JWT token.
  2. API Key Rules:
    If the request is authenticated using an API key, the allowed endpoints and methods are validated against the configuration in appsettings.ApiKey.json.
  3. Policy-Based Access:
    The endpoint’s required policies (e.g., Moderation, Administrative) are checked against the user’s or API key’s assigned policies.
  4. Entity Rights:
    If the user acts as an exhibitor, the corresponding rights (Assigned, Read, Write) for the target entity are verified.
  5. Business Logic:
    Additional rules such as registration deadlines, moderation states, or locked resources are enforced last.

User Impersonation

User impersonation allows privileged users (e.g. administrators or moderators) to temporarily act on behalf of another user.
This mechanism is primarily intended for support, moderation, debugging, and UI inspection scenarios, where reproducing a user-specific context is required without sharing credentials.

The implementation follows a JWT-based impersonation model aligned with common OAuth / token-exchange patterns.
It enforces a strict separation between the acting identity (actor) and the effective identity (subject) while maintaining full auditability and traceability.

Concept and Motivation

Impersonation is designed to:

  • Enable support and moderation workflows without replicating user state on support accounts
  • Allow administrators to reliably reproduce user-facing behavior
  • Inspect role-specific frontends (e.g. moderator tools) without introducing special-case logic
  • Preserve a complete audit trail of who actually performed an action

Impersonation is explicit, temporary, and token-scoped.
At no point is the identity of the acting user lost, overwritten, or implicitly replaced.

JWT Claim Model (Actor vs. Subject)

During impersonation, the JWT contains two distinct identity concepts:

  • Actor
    The real, authenticated user who initiated the impersonation
    (e.g. an administrator or moderator)

  • Subject
    The user being impersonated
    (the effective user identity for authorization checks)

This distinction is reflected in the following claims:

Claim Description
sub The effective user identity (subject)
audit_name The effective user audit string
act.sub Technical identifier of the acting user
act.audit_name Human-readable audit name of the acting user
impersonation Explicit flag indicating an impersonation token (true)
impersonation_id Unique identifier of the impersonation context

Outside of impersonation, only AuditUser is present.

Detecting Impersonation in Frontend Applications

Frontend applications must not infer impersonation implicitly (e.g. via roles or heuristics).

Impersonation is considered active if and only if the claim impersonation is present and set to true.

The claim act.audit_name may be used for display purposes (e.g. banners or warnings), but it must not be used as the sole detection mechanism.

This allows frontend applications to:

  • Clearly indicate impersonation state to the user
  • Avoid accidental privileged actions without user awareness
  • Implement explicit “switch back” or exit flows if supported

The subject identity alone does not indicate impersonation and is always present.

Permission Rules

Impersonation is strictly restricted and evaluated server-side before issuing an impersonation token.

The following rules apply:

  • API key / machine tokens cannot impersonate users
  • Nested impersonation is not allowed
  • Self-impersonation is explicitly prevented
  • Role-based constraints apply:
    • Administrators may impersonate:
      • regular users (Exhibitors)
      • moderators (reserved for future moderator-specific tooling)
    • Moderators may impersonate:
      • regular users (Exhibitors) only
    • Regular users may not impersonate anyone

All checks are performed before issuing an impersonation token.

Audit and Logging Semantics

Impersonation is always recorded in a human-readable and unambiguous format.

Recommended audit identity format:

  • Without impersonation: user@company.de
  • With impersonation: [actor@company.de] impersonating [subject@company.de]

This ensures:

  • Full traceability of privileged actions
  • Clear distinction between actor and subject in logs
  • No ambiguity during incident analysis or support reviews

Troubleshooting Authorization Errors

If you receive an HTTP 403 (Forbidden) even though you are authenticated:

  • Verify your JWT is valid and not expired.
  • Confirm that your user or API key is authorized to access the target entity.
    • Especially for API keys: every endpoint must be explicitly whitelisted.
  • Ensure that no business rule prevents the operation.
    • closed registration window, invalid entity state, etc.
  • Check if the endpoint requires a policy (e.g. [Authorize(Policy = "...")]) that your identity does not fulfill.
  • Verify whether the request is made using an impersonation token:
    • Impersonation JWTs are not refreshable.
    • When an impersonation token expires, the frontend must initiate the refresh flow using the original ( non-impersonated) token.
    • After a successful refresh, a new impersonation JWT must be explicitly requested.
    • Attempting to refresh or reuse an expired impersonation token will result in authorization failures.

Error Handling Model

ProblemDetails and ValidationProblemDetails

  • Errors follow RFC 7807:
    • General errors (e.g., 403, 404, 409, 500).
    • Input validation failures; model state errors are listed with field-specific messages.

Typical status codes by scenario

  • 200 OK: Successful retrieval or update.
  • 201 Created: Successful creation where applicable.
  • 204 No Content: Resource not found for deletion, or empty lists in some retrievals.
  • 400 Bad Request: Invalid identifiers or referenced resources do not exist (with validation details).
  • 401 Unauthorized / 403 Forbidden: Missing authentication or insufficient rights/policy.
  • 404 Not Found: Target entity not found (especially when an ID route parameter is invalid).
  • 409 Conflict: Attempt to modify resources that are “in use” or otherwise conflict with current state.
  • 422 Unprocessable Entity: Payload shape is correct but violates business validation (commonly in media metadata).

Upsert Endpoints (Create/Update in one)

  • Endpoints labeled “Upsert” accept both creates and updates in a single call:
    • If the payload includes a known ID, the resource is updated.
    • If the ID is new or absent, a resource is created.
  • Some resources cannot be updated once “in use” (e.g., assigned or ordered). In such cases, a 409 Conflict is returned with guidance to create a new resource and remove the old one.

Deletion Semantics (Soft vs. Hard Delete)

  • Delete operations may perform:
    • Hard delete: Resource is permanently removed when it is not referenced or “in use”.
    • Soft delete: Resource is marked as removed but retained when it is currently referenced/in use.
  • You may receive:
    • 200 OK when deletion (soft or hard) succeeds.
    • 204 No Content when the target resource does not exist.

Media Management Workflow

  • The API separates metadata registration from binary file upload.

Register metadata first

  • Create or patch media by sending a metadata DTO (name/type/etc.). On success, the API persists metadata and returns links.
  • Short-lived URL for direct upload to the object storage.
  • Limited-time URL for downloading the file.
  • Uploads occur outside the API using the returned link; ensure you upload within the link’s validity window.
  • After the upload to the storage bucket has completed, you must confirm the successful upload via the Media API (upload confirmation endpoint).

Buckets, object keys, and filename sanitization

  • Filenames are sanitized by the server. The final object key is derived from:
    • Uploader type (e.g., event team vs. exhibitor),
    • Entity type (Event/Hall/Booth),
    • Entity ID,
    • Timestamps,
    • Sanitized filename.
  • Buckets may differ based on who uploads (e.g., exhibitor vs. event team).
  • Listing media returns metadata for everyone with basic access to the entity.
  • Download links are included only when the caller has at least Read rights for that entity.

Moderation and rejection notes

  • Several models can be moderated. If rejected, the reason is stored and a notification may be sent.
  • Replacing a file is not supported through patching; to change the binary, delete the media and register/upload again.

Orders and Registration Windows

  • Order updates and certain media edits are disallowed while registration is open/closed based on business rules.
  • If an operation is blocked by the registration window, expect a 403 Forbidden with an explanatory message.

Special DTOs

Some DTOs in this API come in two variants: Up and Down.
This differentiation is necessary to prevent circular dependencies when using automated mapping.

Down DTOs

DTOs with the Down suffix contain enumerations that can potentially build an entire object tree downwards to its smallest entities.
They do not contain back-references upwards.

Up DTOs

DTOs with the Up suffix do not co1ntain downward enumerations.
Instead, they hold a reference to their parent object, representing the upward relationship.

Exhibitor Participation Flow

  • Exhibitors can request participation for an event, which creates a pending booth assignment.
  • Depending on event configuration:
    • If applications are closed, requests will be forbidden.
    • On acceptance or rejection, notifications can be sent to relevant parties.

Event Initialization

For each event, halls and booths can be created in bulk.
To do so, call the Events/{eventId}/Init endpoint and provide the required DTO data.

Behavior & Rules

  • Hall names and booth names must be provided.
  • Duplicate booth names within the same hall will be skipped.
  • Duplicate booth names across different halls are allowed.
  • For each booth, an exhibitor can be assigned by providing the exhibitor’s exact company name.
  • If the system is unable to find a matching exhibitor, a system dummy exhibitor will be assigned automatically.

Conventions and Practical Tips

  • Always check Swagger for shapes of DTOs and routes; use this document to understand the rules that Swagger does not reveal.
  • When you see 400 responses on GET by ID, it typically indicates the ID is invalid for that context (use the response body to locate the invalid field).
  • For 409 Conflict on updates, create a new resource instead and remove the old one if instructed by the error message.
  • For media:
    • Always call the metadata endpoint first.
    • Upload within the provided upload link’s time window.
    • Request a fresh download link if yours expires.
  • For entity-scoped rights, ensure the caller has the correct rights for the specific resource you are targeting.