আপনার অর্গানাইজেশন কোড হিসেবে পরিচালনা করুন
স্ক্রিপ্ট, CI বা Terraform থেকে অর্গানাইজেশনের সদস্য, গ্রুপ, ডিভাইস ট্যাগ, রাউটিং নিয়ম ও API কী পরিচালনা করুন, API, CLI ও Terraform প্রোভাইডারের জন্য একটি অর্গানাইজেশন অ্যাডমিন কী দিয়ে।
Two kinds of key
- An
hlk_key sends. The organization's keys under API keys in the console start Live Activities and send notifications and widgets to its members, the way a personal key does to your own devices. Email they send goes only to the organization's own recipients, never to the members (see Email). - An
hlo_org admin key administers one organization: members, invites, groups, device tags, routing rules, devices and the organization'shlk_keys, plus the audit log, and on the Enterprise plan its verified domains, single sign-on and SCIM provisioning. It sends nothing, and the API refuses it everywhere outside that organization's own endpoints.
Keeping them apart limits what one key can do. The key in your deploy pipeline can page on-call but cannot remove
anyone, and an admin key sends nothing itself. That does not make a manage admin key the safer one to
leak: it can create and roll the organization's hlk_ keys, as the examples below do, and whoever holds
it can send with the keys it makes. Guard it at least as closely as a sending key, and give a job that only reads a read key, which sees no keys at all.
Get an admin key
- Sign in at console.pushward.app as an owner or admin of the organization and open Admin keys.
- Choose New admin key. Give it a name, which shows in the list and in the audit log next to every change it makes, a level, and an expiry if you want one.
- Copy the secret. It is shown once.
| Level | Acts as | Can do |
|---|---|---|
read | Viewer | Reads the organization, members, devices, groups, tags, routing rules, the audit log, the plan and invoices. No invites, no keys, no changes. |
manage | Admin | Also invites and removes members and viewers and changes their roles, renames the organization, and manages groups, tags, routing rules and hlk_ keys. |
Roll gives a key a new secret and the old one stops working at once. Revoking a key also revokes the
invites it created, and so does lowering it from manage to read.
A key lasts only as long as its creator may manage keys. When the person who created it leaves the organization, is removed, loses admin rights (becomes a billing member, member or viewer) or deletes their account, the key stops working and the invites it sent are revoked with it. An owner who is made an admin keeps theirs.
CLI
Install the pushward CLI and give it the admin key. It keeps it next to your sending
key in the same config file. Only pushward org commands use it; everything else still sends with the hlk_ key. The org commands and auth login --org need CLI 1.10.0 or later;
an older one says they are unknown, so update it first.
pushward auth login --org # prompts for the hlo_ key and checks it
export PUSHWARD_ORG_API_TOKEN=hlo_... # or this, which wins over the stored one
pushward auth status # shows both keys and where each one comes fromThe organization comes from the key, so no command takes an org id. Invite someone by email, make a group, and create a sending key for CI that reaches only that group:
pushward org member invite [email protected] --role member
pushward org group create oncall --description "Primary on-call"
pushward org member list
pushward org group set-members <group-id> <user-id> <user-id>
pushward org key create ci --activities manage --notifications schedule --target-group-ids <group-id> --jq .keyorg key create prints the new secret once; --jq .key prints nothing else, so you can pipe it
straight into your secret store. Deletes and revokes run without asking, except org sso delete (--yes skips its prompt). The other commands are org get and org update, org member list|get|invite|update|remove, org invite, org key, org group, org tag, org route, org device, org audit list, org billing get|invoices|invoice, and on the
Enterprise plan org domain, org sso and org audit export (below); add --help to any of them for its flags.
Terraform
The mac-lucky/pushward provider takes the admin key as api_key, or from PUSHWARD_ORG_API_TOKEN when that is not
set. Like the CLI, it finds the organization from the key.
terraform {
required_providers {
pushward = {
source = "mac-lucky/pushward"
}
}
}
# api_key falls back to PUSHWARD_ORG_API_TOKEN.
provider "pushward" {}locals {
team = {
"[email protected]" = "member"
"[email protected]" = "member"
}
}
# Each address gets an invite by email.
resource "pushward_org_member" "team" {
for_each = local.team
email = each.key
role = each.value
}
resource "pushward_org_group" "oncall" {
name = "oncall"
# Pending members have no user_id yet; compact() leaves them out
# and the first apply after they join adds them.
member_ids = compact([for m in pushward_org_member.team : m.user_id])
}
resource "pushward_org_tag" "wall" {
name = "wall"
description = "The iPad on the office wall"
}
resource "pushward_org_key" "ci" {
name = "ci"
permissions = {
activities = "manage"
notifications = "send"
}
target = {
group_ids = [pushward_org_group.oncall.id]
tag_ids = [pushward_org_tag.wall.id]
}
# Change the input to rotate: Terraform replaces the key and its secret.
lifecycle {
replace_triggered_by = [terraform_data.ci_key_rotation]
}
}
resource "terraform_data" "ci_key_rotation" {
input = "2026-11"
}
output "ci_key" {
value = pushward_org_key.ci.secret
sensitive = true
}- Resources:
pushward_org_member,pushward_org_group,pushward_org_tag,pushward_org_route,pushward_org_route_order(the order rules are checked in) andpushward_org_key. Data sources:pushward_org,pushward_org_membersandpushward_org_devices. - A plan with a
pushward_org_keyor a pending member needs amanagekey, since areadkey sees neither keys nor open invites. - The secret of a key is known only when Terraform creates it, and it is kept in the state. Keep the state private. After an import the secret is null.
- A key's
targetis set once: changing it replaces the key, and with it the secret. - The provider creates tags but does not put devices in them. Do that in the console or with
pushward org tag devices. - Each resource records its organization in
org_id. A plan run with another organization's admin key fails with an error instead of touching the resource, so it never reads as gone and gets created again over there. - Create the key Terraform uses from an owner account and leave it without an expiry if the configuration runs for good. To rotate it, roll it in the console. Rolling keeps the key and the invites it sent; replacing it with a new key and revoking the old one revokes those invites, and every pending member gets a new one.
Invited members
An invite by email, from the CLI or from pushward_org_member, goes like this:
- PushWard mails a one-use invite link to the address. The code is only in that mail; the API and the CLI never print it.
- The member is
pendingand has nouser_id, so the group above leaves them out for now. - They open the link, sign in with the Apple or Google account they use in the PushWard app, and join. The address you typed stays on the member as an unverified label; it is never how they sign in.
- The next plan shows them as
joinedwith auser_id, and that apply puts them in the group. Nothing else in the configuration changes.
An invite works for 7 days unless you pass --expires-in to the CLI (up to 30 days). One that expires or
is revoked before anyone joins drops out of the Terraform state, and so does a member who leaves or is removed: the
next apply mails a new invite. While a member is pending, changing their email or role revokes the invite and mails a new one. An address can belong to only one member or open invite of the organization.
The open invites belong to the admin key that sent them. If that key is revoked or lowered to read, or
stops working because its creator left, was removed, lost admin rights or deleted their account, its invites are
revoked and plans with pending members fail. Once a working manage key is configured, those members drop
out of the state and the next apply mails each of them a new invite.
Once someone joins, the address stays on the member as their label until an owner or admin changes it or they leave
or are removed; the invite's own copy is cleared 30 days after the invite ends (see the privacy policy).
Enterprise: domains and single sign-on
On the Enterprise plan the same admin key verifies the organization's email domains, turns single sign-on on and off and exports the audit log. These commands need CLI 1.12.0 or later:
pushward org domain add example.com # prints the TXT record to publish
pushward org domain verify example.com --wait 30m # tries again every 15s until the record shows up
pushward org domain list
pushward org sso show # the redirect URI, or the SAML values to register
pushward org sso set --enabled --require-sso # flags left out keep their stored value
pushward org sso delete # asks first; --yes skips that
pushward org audit export --from 2026-01-01 --to 2026-04-01 -o audit.csvorg sso set also takes --protocol oidc --issuer ... --client-id ... --client-secret-stdin or --protocol saml --metadata-file ... (or --metadata-url); the client secret is read from stdin,
never from a flag. Only an owner sets up single sign-on or changes its identity provider, and an admin key acts as an
admin at most, so those get 403 from a key. An owner sets the connection up in the console; keys turn it
on and off, change --require-sso and replace the client secret. org audit export takes a date
(midnight UTC) or an RFC 3339 time, up to 366 days, and saves under the server's file name unless -o says
otherwise (-o - for stdout).
In Terraform, pushward_org_domain claims a domain and gives its TXT record, pushward_org_domain_verification waits until PushWard sees the record (10 minutes by default), and pushward_org_sso_connection holds single sign-on. Import the connection an owner set up, then let
Terraform turn it on, require it and roll the client secret:
resource "pushward_org_domain" "example" {
domain = "example.com"
}
# The TXT record, here in Route 53; any DNS provider's record works the same way.
resource "aws_route53_record" "pushward" {
zone_id = var.zone_id
name = pushward_org_domain.example.txt_name
type = "TXT"
ttl = 300
records = [pushward_org_domain.example.txt_value]
}
resource "pushward_org_domain_verification" "example" {
domain_id = pushward_org_domain.example.id
depends_on = [aws_route53_record.pushward]
}
# Set up by an owner in the console, then:
# terraform import pushward_org_sso_connection.this <org id>
resource "pushward_org_sso_connection" "this" {
protocol = "oidc"
enabled = true
require_sso = true
oidc = {
issuer = "https://login.example.com"
client_id = "pushward"
# Never in the plan or state (Terraform 1.11 or newer). Bump the
# version to send a rolled secret.
client_secret_wo = var.sso_client_secret
client_secret_wo_version = 1
}
# Turning it on needs a verified domain.
depends_on = [pushward_org_domain_verification.example]
}
variable "sso_client_secret" {
type = string
sensitive = true
ephemeral = true
}- A SAML connection takes
protocol = "saml"andsaml = { idp_metadata_url = "..." }(oridp_metadata_xml) instead ofoidc. With neither attribute,saml = {}keeps the identity provider PushWard has stored and never sends metadata, so Terraform manages onlyenabledandrequire_sso: the form for an imported SAML connection, also one an owner set up from an uploaded metadata document. Its read-onlyacs_urlandsp_entity_id, andredirect_urifor OpenID Connect, are the values to register at the identity provider. - PushWard never returns the client secret, so a secret changed in the console does not show up in a plan.
- When a domain lapses (seven missed daily checks), its
pushward_org_domain_verificationstays in the state and the domain'sstatusshowspending, so a plain apply changes nothing. Fix the TXT record, thenterraform apply -replace=pushward_org_domain_verification.exampleverifies it again. Destroying the verification changes nothing in PushWard; destroying the domain removes it. - The SCIM key is an ordinary
hlo_key at levelmanage; see The SCIM key for why an owner should create it.
What stays in the console
No admin key can do these, at any level. They need a person with the right role signed in to the console:
- Billing changes: subscribing, seats, the billing interval, the payment method, canceling and resuming. An admin key at either level can read the plan and download invoices.
- Owners, admins and billing members. Admin keys grant and manage the member and viewer roles only.
- Admin keys themselves: creating, changing, rolling and revoking them.
- Setting up single sign-on or changing its identity provider (Enterprise). Keys can turn it on and off, require it and replace the client secret.
- Deleting the organization.
- The notice email, the address that warnings about the organization go to.
What stays on the device
Some settings belong to each member's own devices, and no key reaches them: the level per source, sounds, critical alert volume, notification retention and trusted links. Members set them in the PushWard app on each device. The organization decides what it sends and who gets it; how a device presents it is up to its owner.