Chuyển đến nội dung

Quản lý tổ chức dưới dạng mã

Quản lý thành viên, nhóm, thẻ thiết bị, quy tắc định tuyến và khóa API của tổ chức từ script, CI hoặc Terraform, bằng khóa quản trị của tổ chức cho API, CLI và provider 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's hlk_ 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

  1. Sign in at console.pushward.app as an owner or admin of the organization and open Admin keys.
  2. 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.
  3. Copy the secret. It is shown once.
LevelActs asCan do
readViewerReads the organization, members, devices, groups, tags, routing rules, the audit log, the plan and invoices. No invites, no keys, no changes.
manageAdminAlso 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 from

The 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 .key

org 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.

versions.tf
terraform {
  required_providers {
    pushward = {
      source = "mac-lucky/pushward"
    }
  }
}

# api_key falls back to PUSHWARD_ORG_API_TOKEN.
provider "pushward" {}
main.tf
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) and pushward_org_key. Data sources: pushward_org, pushward_org_members and pushward_org_devices.
  • A plan with a pushward_org_key or a pending member needs a manage key, since a read key 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 target is 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:

  1. 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.
  2. The member is pending and has no user_id, so the group above leaves them out for now.
  3. 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.
  4. The next plan shows them as joined with a user_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.csv

org 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:

sso.tf
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" and saml = { idp_metadata_url = "..." } (or idp_metadata_xml) instead of oidc. With neither attribute, saml = {} keeps the identity provider PushWard has stored and never sends metadata, so Terraform manages only enabled and require_sso: the form for an imported SAML connection, also one an owner set up from an uploaded metadata document. Its read-only acs_url and sp_entity_id, and redirect_uri for 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_verification stays in the state and the domain's status shows pending, so a plain apply changes nothing. Fix the TXT record, then terraform apply -replace=pushward_org_domain_verification.example verifies it again. Destroying the verification changes nothing in PushWard; destroying the domain removes it.
  • The SCIM key is an ordinary hlo_ key at level manage; 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.