Xác thực

PushWard sử dụng xác thực bằng Bearer token. Khi bạn đăng nhập bằng Apple ID, một khóa tích hợp mặc định (hlk_) sẽ được tạo tự động -- hãy sao chép nó từ phần cài đặt của ứng dụng để bắt đầu sử dụng API ngay lập tức. Bạn cũng có thể tạo thêm các khóa tích hợp có phạm vi giới hạn cho từng dịch vụ riêng lẻ.

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

⚠ Cảnh báo

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. Cannot create or delete activities.
`activity:manage`	Everything `activity:update` can do, plus create and delete activities.

If your integration creates its own activities, use activity:manage; use activity:update for keys that should only push updates to activities created elsewhere.

Each key can additionally restrict access to specific activity slugs or prefix patterns (trailing *) and toggle three 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.
emails — permit sending email (POST /emails). Independent of notifications; toggle per key in the iOS app's integration-keys screen.

Endpoints

GET /auth/me

Get the current user's profile, activity count, and current quota usage.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nickname": "Alice",
  "activity_count": 3,
  "subscribed": false,
  "quota_period_month": 202606,
  "notifications_used": 128,
  "notifications_limit": 500,
  "live_activity_updates_used": 86,
  "live_activity_updates_limit": 250,
  "widget_updates_used": 12,
  "widget_updates_limit": 50,
  "emails_used": 3,
  "emails_limit": 500,
  "quota_resets_at": "2026-07-01T00:00:00Z"
}

ℹ Thông tin

Integration keys read their own live usage here — the iOS app polls /auth/me for its Usage screen and integrations (e.g. Home Assistant) surface the same counters. A *_limit field is omitted when that resource is uncapped on your tier. (Detailed subscription fields are only returned to the app's own session, not to integration keys.)

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
`quota_period_month`	integer	`YYYYMM` bucket for the current monthly usage period (UTC)
`notifications_used` / `notifications_limit`	integer	Notifications sent this period and your tier's cap. `*_limit` is omitted when uncapped.
`live_activity_updates_used` / `live_activity_updates_limit`	integer	Live Activity updates this month and your tier's cap
`widget_updates_used` / `widget_updates_limit`	integer	Widget updates this month and your tier's cap
`emails_used` / `emails_limit`	integer	Emails sent this month and your tier's cap (free 500, paid 2,500)
`quota_resets_at`	string	ISO 8601 instant the active counters reset

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}`
`hlk_` with `emails` flag	`POST /emails`