Authentication

PushWard uses Bearer token authentication. When you sign in with Apple ID, a default integration key (hlk_) is automatically created -- copy it from the app's settings to start using the API immediately. You can also create additional scoped integration keys for individual services.

Token Format

Integration keys use the hlk_ prefix followed by 32 base62 characters (~36 characters total). Only the SHA-256 hash is stored server-side -- tokens cannot be recovered if lost.

Authorization: Bearer hlk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

⚠ Warning

Integration keys are shown only once when created. Store them securely -- they cannot be recovered if lost.

Managing Keys

Create and revoke integration keys in the iOS app's settings screen. A default activity:manage key is created automatically on first sign-in.

Scopes

Scope	Access
`activity:update` (default)	Update existing activities and read state
`activity:manage`	All of `activity:update`, plus create and delete activities

Each key can additionally restrict access to specific activity slugs or prefix patterns (trailing *) and toggle two independent permission flags:

notifications — permit POST /notifications.
widgets — permit the widgets API (POST/GET/PATCH/DELETE /widgets). Off by default; toggle per key in the iOS app's integration-keys screen.

Endpoints

GET /auth/me

Get the current user's profile, activity count, and subscription status.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nickname": "Alice",
  "activity_count": 3,
  "subscribed": true,
  "subscription_status": "active",
  "product_id": "com.maclucky.pushward.pro",
  "expires_at": "2026-07-15T00:00:00Z"
}

Response Fields

Field	Type	Description
`id`	string	User ID
`nickname`	string \| null	Display name
`activity_count`	integer	Number of activities owned by the user
`subscribed`	boolean	Whether the user has an active subscription
`subscription_status`	string \| null	Subscription status (e.g. `"active"`, `"expired"`). Omitted if no subscription.
`product_id`	string \| null	App Store product identifier. Omitted if no subscription.
`expires_at`	string \| null	Subscription expiry timestamp (ISO 8601). Omitted if no subscription.

Access Control

Access Level	Endpoints
No auth	`GET /health`
`hlk_` with `activity:update`	`PATCH /activities/{slug}` (owned activities only), `GET /activities`, `GET /activities/{slug}`, `POST /notifications` (if the key has the `notifications` flag), `GET /auth/me`
`hlk_` with `activity:manage`	All of the above, plus `POST /activities`, `DELETE /activities/{slug}`
`hlk_` with `widgets` flag	`POST /widgets`, `GET /widgets`, `GET /widgets/{slug}`, `PATCH /widgets/{slug}`, `DELETE /widgets/{slug}`