Authentication

Two-tier authentication

The API distinguishes between two types of credentials, each granting access to different sets of endpoints:

Both credential types are passed in the Authorization header using the Bearer scheme. For compatibility during development, the API also accepts the legacy X-App-Api-Key and X-User-Token headers, but Authorization: Bearer ... is the preferred long-term contract.

Authorization: Bearer YOUR_API_KEY_OR_USER_TOKEN

API Keys

API keys authenticate your application at the server level. They are used exclusively for user management operations -- creating, reading, updating, and deleting users.

Creating an API key

Follow these steps to create a new API key:

Using an API key

Include the API key in the Authorization header for all user management requests:

curl -X POST \
  https://health-api.movetohappiness.com/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-123",
    "locale": "en-US",
    "timezone": "Europe/Brussels"
  }'

If a request is made without a valid key, or to an endpoint that requires a user token instead, the API returns a 401 Unauthorized response.

User Tokens

User tokens authenticate individual users and grant access to their scoped data. They are used for connections management, nutrition journaling, health scores retrieval, and any other user-specific operations. User tokens authenticate the individual user making the request.

For nutrition journaling, the user token is also what you use to create dedicated Water and Coffee entries in addition to meals and generic drinks.

Obtaining a user token

A user token is automatically generated and included in the response when you create a user via POST /api/v1/users. That endpoint is idempotent: it returns 201 Created for a new user, or 200 OK if the externalUserId already exists and a fresh token is issued for the existing user. In both cases, the token appears in the token field:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "appId": "e5f6g7h8-i9j0-1234-klmn-op5678901234",
  "externalUserId": "user-123",
  "status": "Active",
  "token": "usr_tok_abc123def456ghi789...",
  ...
}

Store this token securely in your backend. You will pass it as a Bearer token for all user-scoped API calls.

Using a user token

Include the user token in the Authorization header for connections, journal, and scores requests:

curl -X GET \
  "https://health-api.movetohappiness.com/api/v1/scores/daily?from=2026-03-10&to=2026-03-15" \
  -H "Authorization: Bearer usr_tok_abc123def456ghi789..."

curl -X POST \
  https://health-api.movetohappiness.com/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/journal-entries \
  -H "Authorization: Bearer usr_tok_abc123def456ghi789..." \
  -H "Content-Type: application/json" \
  -d '{
    "entryKind": "Coffee",
    "nutrients": { "caffeineMg": 95, "volumeMl": 240 }
  }'

Valid journal entryKind values are Meal, Drink, Water, and Coffee.

Rotating a user token

If a user token is compromised or you want to rotate it as a security measure, use the rotate-token endpoint. This invalidates the old token and returns a new one:

curl -X POST \
  https://health-api.movetohappiness.com/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rotate-token \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "token": "usr_tok_new123xyz456abc789..."
}

Security best practices