User Sync

When a user updates their profile in sphere-auth (name, email, locale, timezone), sphere-auth calls sphere-core to synchronize these changes. This ensures that user data remains consistent across the platform without requiring the user to update their profile in each service independently.

This is an internal service-to-service API authenticated with HMAC signatures. It is not exposed through the Traefik gateway. See the HMAC overview for authentication details.

PATCH/core/api/v1/users/by-auth-id/{authUserId}

Sync user data

Update user profile data in sphere-core by looking up the user via their auth user ID. This is a tenant-wide lookup -- the user is found regardless of which workspace they belong to.

This endpoint is called by sphere-auth whenever a user profile is updated. It uses HMAC authentication rather than a user JWT because it is a service-to-service call triggered by the auth service.

Path parameters

Name
authUserId
Type
string (UUID)
Description
The user's ID in sphere-auth. This is used to look up the corresponding user record in sphere-core.

Optional attributes

All attributes are optional. Only include the fields that have changed.

Name
first_name
Type
string
Description
Updated first name.
Name
last_name
Type
string
Description
Updated last name.
Name
email
Type
string
Description
Updated email address.
Name
locale
Type
string
Description
Updated locale code (e.g., fr_FR, en_US).
Name
timezone
Type
string
Description
Updated timezone (e.g., Europe/Paris, America/New_York).

Request

PATCH

/core/api/v1/users/by-auth-id/{authUserId}

curl -X PATCH http://core:7002/api/v1/users/by-auth-id/a7c8e9f0-1234-5678-abcd-ef0123456789 \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "first_name": "Alice",
    "last_name": "Dupont",
    "email": "alice.dupont@acme.local",
    "locale": "fr_FR",
    "timezone": "Europe/Paris"
  }'

Response

{
  "data": {
    "id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
    "auth_user_id": "a7c8e9f0-1234-5678-abcd-ef0123456789",
    "first_name": "Alice",
    "last_name": "Dupont",
    "email": "alice.dupont@acme.local",
    "locale": "fr_FR",
    "timezone": "Europe/Paris",
    "updated_at": "2026-01-20T14:30:00Z"
  }
}

Response (404 - user not found)

{
  "message": "User not found for auth_user_id: a7c8e9f0-1234-5678-abcd-ef0123456789"
}