API: Users
===========

Base URL: ``/users``

User management endpoints. Users are auto-created from JWT tokens on first
API interaction.

Endpoints
----------

Get Current User
~~~~~~~~~~~~~~~~~

.. code-block:: http

   GET /users/me

Returns the authenticated user's profile.

**Response (200):**

.. code-block:: json

   {
     "id": "uuid",
     "name": "Alice",
     "createdAt": "2026-01-10T08:00:00Z"
   }

Authentication
---------------

The platform supports two authentication methods:

**1. Bearer JWT Token (Preferred):**

.. code-block:: http

   Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The backend decodes the JWT and extracts:

- ``user_id`` or ``sub`` claim → User ID
- ``preferred_username`` / ``name`` / ``given_name + family_name`` → Display name

**2. Header-Based (Development/Service-to-Service):**

.. code-block:: http

   X-User-Id: user-001
   X-User-Name: Alice

User Auto-Creation
~~~~~~~~~~~~~~~~~~~

On first API call with a new user ID, the backend automatically:

1. Creates a ``User`` record with the extracted ID and name
2. Returns the user context for subsequent service calls

No explicit registration endpoint is required.

Name Resolution Priority
~~~~~~~~~~~~~~~~~~~~~~~~~~

The display name is resolved in order:

1. ``preferred_username`` JWT claim
2. ``name`` JWT claim
3. ``given_name`` + ``family_name`` JWT claims
4. ``X-User-Name`` header
5. Falls back to user ID