Autenticazione
Autenticazione Bearer con chiavi di integrazione (hlk_): l'accesso con l'ID Apple crea una chiave predefinita, e puoi aggiungere chiavi con ambito limitato per ogni servizio.
Token Format
A key is hlk_ followed by 32 base62 characters (~36 characters total). Only the SHA-256 hash is stored server-side, so a lost key cannot be recovered.
Authorization: Bearer hlk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345Permissions
Each key has one permission level per resource. A higher level includes the lower ones.
| Resource | Levels | Access | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
activities | none, read, update, manage | read: list and get activities. update: also update existing ones. manage: also create and delete them, and PATCH ?upsert=true. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notifications | none, send, schedule | send: POST /notifications and reading answers. schedule: also the scheduled notifications endpoints. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
widgets | none, read, write | read: list and get widgets. write: also create, update and delete them (widgets API). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
emails | none, send | send: send email (POST /emails) to verified recipients. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| In arrivo nella versione 1.21.0 dell'app su iPhone, iPad e Mac, e nella versione 1.3.0 su Android | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
devices | none, read, manage | read: list and get the account's devices and see which activities each one follows. manage: also rename and remove devices and change what they follow. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sharing | none, read, manage | read: list the shares you granted and the ones you received. manage: also share activities and slug patterns, change a share's role and revoke shares. Granting and changing a role need a subscription. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
account | none, read, manage | read: see whether Setup tips is on and list the account's email recipients. manage: also change the nickname (PATCH /auth/me), turn Setup tips on or off, and add, remove and re-confirm recipients. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
devices, sharing and account reach the account itself rather than what it sends, so they are opt-in: every key starts at none on all three, the default key too, and only the app raises them. In the iOS app they are in the Account Access section when you create a key and in a key's detail under Manage Keys, where the default key is listed first. On Android they are in the Account access section of a key's create and detail screens, and the default key's are under Settings → Integration Key. Over the API the default key can pass them on to keys it creates or updates, up to its own level and no higher (403 integration_key.grant_exceeded). Organization keys cannot have them: asking for one gets 422 org.key_permission_unavailable.
A key can also be limited to specific activity slugs (activity_slugs) and widget slugs (widget_slugs), exact or as a prefix with a trailing *, and can have an expiry (expires_at). An expired key gets 401 with code integration_key.expired; a request above the key's levels gets 403 with code integration_key.permission_denied and a detail naming the level it needs, such as requires widgets:write. GET /auth/me works with every key and reports the calling key's permissions under integration_key.
Keys created before permission levels existed keep exactly the access they had. The older fields are still returned and accepted. In responses, scope is activity:<level>, and notifications is true at send or above, widgets at write and emails at send. In a create or update, true means the resource's highest level and false means none; send either those fields or permissions, not both.
Keys of an organization are made in its console and can also be limited to some groups and device tags: they then send only inside them and see only the activities sent inside them (details).
Creating scoped keys
The default key has activities, notifications, widgets and emails at their highest level, which is all most integrations need. To limit a service to what it uses, create a dedicated key:
- Open Settings → Manage Keys in the iOS app — the same screen revokes existing keys.
- Tap +.
- Set a name, choose what the key may do, and optionally limit it to slugs such as
grafana-*. - Copy the generated
hlk_key and store it securely -- it is shown only once.
Questa sezione descrive una funzionalità di un aggiornamento dell'app in attesa di revisione su App Store. Si sblocca qui automaticamente non appena l'aggiornamento è disponibile.
The app sets a level for each resource, with presets such as Notifications only, and can limit a key to widget slugs and give it an expiry.


Tap a key to change its levels, slug limits or expiry later; each change saves right away. The default key's levels, slug limits and expiry stay fixed.
Tap a key to change its levels, slug limits or expiry later; each change saves right away. On the default key only the devices, sharing and account levels change; its other levels, slug limits and expiry stay fixed.
Questa sezione descrive una funzionalità di un aggiornamento dell'app in attesa di revisione su App Store. Si sblocca qui automaticamente non appena l'aggiornamento è disponibile.
The default key is not listed in Manage Keys: it always has every resource at its highest level, and the only change it takes is a roll, from Roll Key under Settings → Integration Key.
The default key always has activities, notifications, widgets and emails at their highest level, and starts at none on devices, sharing and account. Besides those three, the only change it takes is a roll, from Roll Key under Settings → Integration Key.
The default key can also create keys over the API (POST /integrations/keys, pushward key create), for example a notifications-only key for an alerting bridge:
curl -X POST https://api.pushward.app/integrations/keys \
-H "Authorization: Bearer $PUSHWARD_DEFAULT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "alerts", "permissions": {"notifications": "send"}, "expires_at": "2027-01-01T00:00:00Z"}'A resource left out of permissions gets none. A key created this way can never have a level above the default key's own.
Endpoints
/auth/meGet 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": 50,
"quota_resets_at": "2026-07-01T00:00:00Z",
"integration_key": {
"id": "0b6f0c1e-5a3d-4c1f-9d0a-6f2e8b7c4a11",
"name": "Grafana",
"is_default": false,
"permissions": {"activities": "none", "notifications": "send", "widgets": "write", "emails": "none"},
"widget_slugs": ["grafana-*"]
}
}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 50, paid 200) |
quota_resets_at | string | ISO 8601 instant the active counters reset |
integration_key | object | The key that made the request: id, name, is_default, permissions, and activity_slugs, widget_slugs and expires_at when set |
Access Control
| Access Level | Endpoints | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| No auth | GET /health | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Any hlk_ key | GET /auth/me | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
activities: read | GET /activities, GET /activities/{slug} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
activities: update | Everything read allows, plus PATCH /activities/{slug} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
activities: manage | Everything update allows, plus POST /activities, DELETE /activities/{slug}, PATCH /activities/{slug}?upsert=true | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notifications: send | POST /notifications, GET /notifications/answers/{id} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notifications: schedule | Everything send allows, plus POST /notifications/scheduled, GET /notifications/scheduled, GET /notifications/scheduled/{id}, DELETE /notifications/scheduled/{id} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
widgets: read | GET /widgets, GET /widgets/{slug} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
widgets: write | Everything read allows, plus POST /widgets, PATCH /widgets/{slug}, DELETE /widgets/{slug} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
emails: send | POST /emails | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| In arrivo nella versione 1.21.0 dell'app su iPhone, iPad e Mac, e nella versione 1.3.0 su Android | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
devices: read | GET /devices, GET /devices/{device_id}, GET /devices/{device_id}/subscriptions, GET /devices/{device_id}/subscriptions/{slug} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
devices: manage | Everything read allows, plus PATCH /devices/{device_id}, DELETE /devices/{device_id}, POST /devices/{device_id}/subscriptions/{slug}, DELETE /devices/{device_id}/subscriptions/{slug} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sharing: read | GET /permissions, GET /activities/{slug}/permissions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sharing: manage | Everything read allows, plus POST /activities/{slug}/permissions, POST /permissions/patterns, PATCH /permissions/{id}, DELETE /permissions/{id} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
account: read | GET /app/onboarding, GET /emails/recipients | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
account: manage | Everything read allows, plus PATCH /auth/me, PATCH /app/onboarding, POST /emails/recipients, POST /emails/recipients/{id}/resend, DELETE /emails/recipients/{id} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||